VRT 2.0 Stefan Seipel, Hans Molin, Lars Winkler Pettersson, Mikael Erlandsson Version 2.0 9/30/2003 i

Transcription

1 VRT 2.0 Stefan Seipel, Hans Molin, Lars Winkler Pettersson, Mikael Erlandsson Version 2.0 9/30/2003 i

2 ii

3 Table of Contents Table of contents VRT Module Index VRT Modules Here is a list of all modules: VRT...1 Scene...1 Lights...1 Node...27 WoW...64 Camera...68 Animation...73 System...12 Rendering...18 Texturing...19 Pipe...61 Shadow...79 Geometry...37 Intersections...23 Polygon...52 Models...54 Network...77 VRT Data Structure Index VRT Data Structures Here are the data structures with brief descriptions: _HPLG (Handle to polygon)...79 _nodepath...80 _patch...81 _VRT_CONTEXT...81 _VRT_DEC_INFO...91 _VRT_DEC_VTX...92 _VRT_DepthMap...92 _VRT_Htx (Handle to texture)...93 VRT_AnimationKnottag (??)...94 VRT_Animationtag (??)...95 iii

4 VRT_Bitmaptag (??)...97 VRT_CB_MSG...98 VRT_Displaytag...99 VRT_Geometrytag (Geometry) VRT_Lighttag VRT_Nodetag (Node) VRT_Pipetag VRT_Polygontag (Polygon) VRT_PPBtag (??) VRT_Projectortag VRT_Vertextag (Vertex) VRT File Index VRT File List Here is a list of all files with brief descriptions: vrt.h vrt_core.h vrt_globals.h vrt_types.h iv

5 VRT Module Documentation VRT Modules Scene System Rendering Geometry Network Scene Modules Lights Node WoW Camera Animation Lights Functions VRT_API void VRT_SetLightModel (int lightmodel) Setting the current light model. VRT_API int VRT_GetLightModel () Retrieving the current light model. VRT_API VRT_Light * VRT_LightNew (int light_type) Create a new light source object. VRT_API int VRT_LightDelete (VRT_Light *light) Delete a light object and free allocated resources. VRT_API int VRT_LightSetColors (VRT_Light *light, float *colors) 1

6 Setting the color parameters of a light source object. VRT_API int VRT_LightGetColors (VRT_Light *light, float *colors) Retrieve color parameters of a light source. VRT_API int VRT_LightSetAttenuation (VRT_Light *light, float *attenuation) Setting the attenuation parameters of a light source object. VRT_API int VRT_LightGetAttenuation (VRT_Light *light, float *attenuation) Retrieves the attenuation factors of a light source. VRT_API int VRT_LightSetSpotParameters (VRT_Light *light, float exponent, float cutoff) Setting the spotlight light cone parameters. VRT_API int VRT_LightGetSpotParameters (VRT_Light *light, float *exponent, float *cutoff) Retrieving the spotlight light cone parameters. VRT_API int VRT_LightSetPosition (VRT_Light *light, float x, float y, float z) Setting the explicite position of a light source object. VRT_API int VRT_LightGetPosition (VRT_Light *light, float *x, float *y, float *z) Get the explicite position of a light source object. VRT_API int VRT_LightSetDirection (VRT_Light *light, float dx, float dy, float dz) Setting the direction of a direction light source object. VRT_API int VRT_LightGetDirection (VRT_Light *light, float *dx, float *dy, float *dz) Get the direction of a direction light source object. VRT_API int VRT_LightSetPositionNode (VRT_Light *light, VRT_Node *nposition) Setting the position node of a light source object. VRT_API VRT_Node * VRT_LightGetPositionNode (VRT_Light *light) Retrieve position node of a light source object. VRT_API int VRT_LightSetTargetNode (VRT_Light *light, VRT_Node *ntarget) Setting the target node of a directional light source object. VRT_API VRT_Node * VRT_LightGetTargetNode (VRT_Light *light) Retreiving the target node of a directional light. VRT_API int VRT_LightSwitchOn (VRT_Light *light) Switching on a light source object. 2

7 VRT_API int VRT_LightSwitchOff (VRT_Light *light) Switching off a light source object. VRT_API int VRT_LightGetSwitchState (VRT_Light *light) Retrieving the current switch state of a light source object. VRT_API int VRT_LightSetType (VRT_Light *light, int light_type) Setting the type of the specified light source object. VRT_API int VRT_LightGetType (VRT_Light *light) Retreives the type of the specified light source object. Function Documentation VRT_API int VRT_GetLightModel () Retrieving the current light model. VRT can perform lighting calculations in two different ways. Global lightning (VRT_GLOBAL_LIGHT_MODEL) calculations, take care about the direction and position of lights in relation to the shaded objects surface attitude. In local lighting calculations (VRT_LOCAL_LIGHT_MODEL), in addition the relation between direction of light and direction from object towards the observer considered in illumination calculations. This gives more realistic shading results at the cost of decreased rendering performance. By default, VRT_GLOBAL_LIGHT_MODEL is installed and should only be changed, if specific illumination effects are desired. VRT_GLOBAL_LIGHT_MODEL or VRT_LOCAL_LIGHT_MODEL VRT_SetLightModel VRT_API int VRT_LightDelete (VRT_Light * light) Delete a light object and free allocated resources. The function removes the light object specified by light from the internal light object list and frees all resources allocated by this object. VRT allows the definition of VRT_LIGHTLIST_MAXLIGHTS different light source objects which are maintained in an internal light list. Lights should only be deleted if they are not used any longer in a simulation. Animation of lights (i.e. switching on and off) should be done using the corresponding switching functions. light a pointer to a light object 1 if function succeeded, otherwise 0 If 0 is returned also a VRT error code was prompted in the console window. 3

8 VRT_LightNew, VRT_LightSwitchOff, VRT_LightSwitchOn VRT_API int VRT_LightGetAttenuation (VRT_Light * light, float * attenuation) Retrieves the attenuation factors of a light source. The function retrieves the three light attenuation parameters of the light source specified by light. Every light source carries three attenuation parameters, which describe the proportion of light attenuation depending on the distance between light source and illuminated object. These parameters describe linear and quadric attenuation factors, which are multiplied by the distance measure. Light attenuation is considered for positional lights only (VRT_LIGHT_POSITIONAL, VRT_LIGHT_SPOT). By default, all light sources have their parameters set to [1.0, 0.0, 0.0], which corresponds to non attenuated light. Note that attenuation pointer actually points to an array of three floating point values. VRT does only check if attenuation pointer is not NULL, otherwise VRT can not determine wheather attenuation points to a sufficiently big memory area. However, VRT checks for correctness of light pointer. The function copies the current parameter set of the specified light source to the attenuation pointer array. light a pointer to a valid light source object attenuation a pointer to an array of three floating point values 1 if function was successful, otherwise 0. VRT_LightSetAttenuation VRT_API int VRT_LightGetColors (VRT_Light * light, float * colors) Retrieve color parameters of a light source. The function retreives the ambient, diffuse and specular color components for the specified light source object. Each color is defined by four floating point values clamped to the range of [ ]. The format in which the color values are returened is: AR, AG, AB, AA, DR, DG, DB, DA, SR, SG, SB, SA Note that colors pointer actually points to an array of twelve floating point values. VRT does only check if colors pointer is not NULL, otherwise VRT can not determine wether colors points to a sufficiently big memory area. However, VRT checks for correctness of light pointer. The function copies the current color parameter set of the specified light source to the colors pointer array. light a pointer to a light source object colors a pointer to 12 floating point color value 1 if function was successful, otherwise 0. VRT_LightSetColors VRT_API int VRT_LightGetDirection (VRT_Light * light, float * dx, float * dy, float * dz) Get the direction of a direction light source object. In VRT, the direction of light is considered for two types of lights: VRT_LIGHT_DIRECTIONAL and VRT_LIGHT_SPOT. For positional light sources, the direction does not care because they radiate to all directions. The directional vector of a light source is defined with regard to the global coordinate system. The explicite directional vector is always used unless the light has a target node 4

9 defined which it is spotting. Initially, all light sources have the directional vector set to [0, -1.0, 0]. The function Retrieves the currently set direction vector of the specified light source object. Take care, that dx, dy, and dz are valid pointers to single floating point values. light a pointer to a light source object dx a pointer to the floating point x component of the directional vector dy a pointer to the floating point y component of the directional vector dz a pointer to the floating point z component of the directional vector 1 if function succeeded, otherwise 0 VRT_LightSetDirection, VRT_LightSetTargetNode VRT_API int VRT_LightGetPosition (VRT_Light * light, float * x, float * y, float * z) Get the explicite position of a light source object. In VRT, the position of light is considered for two types of lights: VRT_LIGHT_POSITIONAL and VRT_LIGHT_SPOT. For directional light sources, the position does not care because they are assumed to be at infinity. The position of a light source is defined with regard to the global co-ordinate system. The explicite position co-ordinates are always used unless the light has a position node defined. Initially, all light sources have the position to [0, 1.0, 0]. Take care, that x, y, and z are valid pointers to single floating point values. light a pointer to a light source object x a pointer to the floating point x coordinate of the position y a pointer to the floating point y coordinate of the position z a pointer to the floating point z coordinate of the position 1 if function succeeded, otherwise 0 VRT_LightSetPosition, VRT_LightSetPositionNode VRT_API VRT_Node* VRT_LightGetPositionNode (VRT_Light * light) Retrieve position node of a light source object. In VRT, light sources can be attached to any node within the scene graph hierarchy. In that way, light position can be animated very easily, by having a light tracking a specific node. Whenever a light source has its position node set to a valid node in the scene graph hierarchy, VRT will transform the position of this node into global universe co-ordinates and override the explicitly set position values with the transformed position of the position node to be tracked. The function returns the pointer to the currently set position node or NULL. light a pointer to a light source object A pointer to a valid node in the scene graph, which is currently being tracked by the light source, or NULL. VRT_LightSetPositionNode 5

10 VRT_API int VRT_LightGetSpotParameters (VRT_Light * light, float * exponent, float * cutoff) Retrieving the spotlight light cone parameters. For spotlights only, an additional set of parameterws is considered in lighting calculations, to pay attention to the cone angle of the spotlight beam and to the attenuation of light from the center of the light cone towards the light cones borders. Light is being attenuated with the cosine of the angle of light rays from the center of the cone beam raised by a number. The exponent is defining this exponential value. By default, the exponent is set to 0 i.e. distribution of light will not be attenuated within the cone beam at all. Valid values for exponent are in the range of [ ]. The cutoff angle defines the opening angle of the light cone measured from the central line of the light direction towards the border of the cone. Objects outside the light cone of a spotlight will not be considered for lighting calculations and will not receive any light from this light source. The initial value for the cutoff angle is 180.0, which means that no spot light at all, instead positional light spreading to all directions. Meaningful values for cutoff are [ ]. The function only can test for NULL pointer input. Make sure that exponent and cutoff are referencing sufficiently allocated memory. light a pointer to a light source object exponent a pointer to a floating point exponent parameter cutoff a pointer to a floating point cutoff angle parameter 1 if function succeeded, otherwise 0 VRT_LightSetSpotParameters VRT_API int VRT_LightGetSwitchState (VRT_Light * light) Retrieving the current switch state of a light source object. In VRT lights can be switched on and off in order to flexibly allow for changes in illumination settings. The function returns the current switch state for a light source. Note: There can be at most MAX_GL_LIGHTS simultaneously activated light sources in the scene. The actual value depends on the OpenGL implementation by is usually 8. light a pointer to a light source object 1 - if light is switched on 0 - if light is switched off,or if light is invalid VRT_LightSwitchOn, VRT_LightSwitchOff VRT_API VRT_Node* VRT_LightGetTargetNode (VRT_Light * light) Retreiving the target node of a directional light. In VRT, directional light sources can automatically track an object. By setting a target node to a directional light source object, VRT automatically calculates the light sources direction. Regardles wether the position of the light source is defined explicitely or by tracked with a position node, the direction is calculated from the lightâ s position towards the target node. The automatically calculated direction is overriding the explicitly set direction vector. This feature allows for easy animation of light direction in the case of directional light sources. Any movement of the target node will cause light to automatically follow. Direction tracking can be de-activated by setting NULL to the target node of a light source object. This function retrieves the currently set target node of the specified light source object. 6

11 light a pointer to a light source object A pointer to a valid node in the scen-graph hierarchy or NULL if not available. VRT_LightSetTargetNode, VRT_LightSetDirection, VRT_LightGetDirection VRT_API int VRT_LightGetType (VRT_Light * light) Retreives the type of the specified light source object. VRT can handle three different types of light sources: VRT_LIGHT_DIRECTIONAL: Directional light is located a infinity and has a specific direction. It is a global light which is not attenuated over distance. VRT_LIGHT_POSITIONAL : Positional light has a dedicated puctual position in the scene and emitts light towards all directions from this point. Unlike directional light, positional light is a local light and can be attenuated with distance depending on its attenuation parameters. VRT_LIGHT_SPOT: Spotlights have both a specific location in the scene and sprread light towards a limited are around a specific direction. Spotlights are local lights and can be attenuated with distance depending on their attenuation parameters. The amount of light distribution around the main light direction can be controlled with the exponent and cutoff parameters of the spotlight object. The function returns one of these typea of light for the specified light source. light a pointer to a light source object VRT_LIGHT_DIRECTIONAL VRT_LIGHT_POSITIONAL VRT_LIGHT_SPOT VRT_LightSetType, VRT_LightNew VRT_API VRT_Light* VRT_LightNew (int light_type) Create a new light source object. The function creates a new light source object, allocates the required resources and adds the light source object to the list of currently defined lights. VRT allows the definition of VRT_LIGHTLIST_MAXLIGHTS (currently 32) different light source objects which are maintained in an internal light list. Observe howerver, that at most MAX_GL_LIGHTS (depending on OpenGL implementation. Usually 8) light sources can be activated simultaneously in the scene. If the internal list of lights is full upon creation of a new light source, a corresponding error will be prompted in the console window of VRT and a NULL pointer will be returned. Otherwise, the function will return a pointer to the light source object. The light type can be either one of: VRT_LIGHT_DIRECTIONAL: Directional light is located a infinity and has a specific direction. It is a global light which is not attenuated over distance. VRT_LIGHT_POSITIONAL: Positional light has a dedicated puctual position in the scene and emitts light towards all directions from this point. Unlike directional light, positional light is a local light and can be attenuated with distance depending on its attenuation parameters. VRT_LIGHT_SPOT: Spotlights have both a specific location in the scene and sprread light towards a limited are around a specific direction. Spotlights are local lights and can be attenuated with distance depending on their attenuation parameters. After creation of a light, it type can still be modified. Observe howerver, that the light parameters of lights (position, direction..) do have different relevance for different types of light. After creation of a new light source, the position is set to [ ] and the direction is set to [ ]. Note: Light source objects created with thisa function must be deleted with the function VRT_LightDelete and must not be re-allocated by the calling process. 7

12 light_type an integer value identifying the light type A pointer to a valid light source object if successfully, otherwise a NULL pointer. VRT_LightDelete, VRT_LightSetType VRT_API int VRT_LightSetAttenuation (VRT_Light * light, float * attenuation) Setting the attenuation parameters of a light source object. The function sets the three light attenuation parameters of the light source specified by light. Every light source carries three attenuation parameters, which describe the proportion of light attenuation depending on the distance between light source and illuminated object. These parameters describe linear and quadric attenuation factors, which are multiplied by the distance measure. Light attenuation is considered for positional lights only (VRT_LIGHT_POSITIONAL, VRT_LIGHT_SPOT). By default, all light sources have their parameters set to [1.0, 0.0, 0.0], which corresponds to non attenuated light. Note that attenuation pointer actually points to an array of three floating point values, which are initialized to reasonable values (e.g. [ ]). VRT does only check if attenuation pointer is not NULL, otherwise VRT can not determine wheather attenuation points to a sufficiently big memory area. However, VRT checks for correctness of light pointer. The function copies the values referenced by the attenuation pointer into the local parameter set of the specified light source. light a pointer to a valid light source object attenuation a pointer to an array of three floating point values 1 if function was successful, otherwise 0. VRT_LightGetAttenuation VRT_API int VRT_LightSetColors (VRT_Light * light, float * colors) Setting the color parameters of a light source object. The function sets the ambient, diffuse and specular color components for the specified light source object. Each color is defined by four floating point values clamped to the range of [ ]. The format in which the color values are returened is: AR, AG, AB, AA, DR, DG, DB, DA, SR, SG, SB, SA Note that the colors pointer actually points to an array of twelve floating point values. VRT does only check if colors pointer is not NULL, otherwise VRT can not determine wether colors points to a sufficiently big memory area. However, VRT checks for correctness of light pointer. The function copies the values referenced by the colors pointer array into the local parameter set of the specified light source. light a pointer to a light source object colors a pointer to 12 floating point color value 1 if function was successful, otherwise 0. VRT_LightGetColors 8

13 VRT_API int VRT_LightSetDirection (VRT_Light * light, float dx, float dy, float dz) Setting the direction of a direction light source object. In VRT, the direction of light is considered for two types of lights: VRT_LIGHT_DIRECTIONAL and VRT_LIGHT_SPOT. For positional light sources, the direction does not care because they radiate to all directions. The directional vector of a light source is defined with regard to the global coordinate system. The explicite directional vector is always used unless the light has a target node defined, which it is spotting. Initially, all light sources have the directional vector set to [0, -1.0, 0]. The function can be used to explicitely set the values of the direction vector components. The vector does not need to be normalized. light a pointer to a light source object dx a floating point value for the x component of the directional vector dy a floating point value for the y component of the directional vector dz a floating point value for the z component of the directional vector 1 if function succeeded, otherwise 0 VRT_LightGetDirection, VRT_LightSetTargetNode, VRT_LightGetTargetNode VRT_API int VRT_LightSetPosition (VRT_Light * light, float x, float y, float z) Setting the explicite position of a light source object. In VRT, the position of light is considered for two types of lights: VRT_LIGHT_POSITIONAL and VRT_LIGHT_SPOT. For directional light sources, the position does not care because they are assumed to be at infinity. The position of a light source is defined with regard to the global co-ordinate system. The explicite position co-ordinates are always used unless the light has a position node defined. Initially, all light sources have the position to [0, 1.0, 0]. This function sets explcitely the positional values of the specified light source object. light a pointer to a light source object x a floating point value for the x coordinate of the position y a floating point value for the y coordinate of the position z a floating point value for the z coordinate of the position 1 if function succeeded, otherwise 0 VRT_LightGetPosition, VRT_LightSetPositionNode, VRT_LightGetPositionNode VRT_API int VRT_LightSetPositionNode (VRT_Light * light, VRT_Node * nposition) Setting the position node of a light source object. In VRT, light sources can be attached to any node within the scene graph hierarchy. In that way, light position can be animated very easily, by having a light tracking a specific node. Whenever a light source has its position node set to a valid node in the scene graph hierarchy, VRT will transform the position of this node into global universe co-ordinates and override the explicitly set position values with the transformed position of the position node to be tracked. The function sets the position node of a the specified light source to the node passed on by nposition. If automatic position tracking of a light source shall be discontinued, the function can be called again with NULL pointer for the nposition parameter. 9

14 light a pointer to a light source object nposition a valid node of the scene graph to which the light sources position is tracked 1 if function succeeded, otherwise 0 VRT_LightGetPositionNode VRT_API int VRT_LightSetSpotParameters (VRT_Light * light, float exponent, float cutoff) Setting the spotlight light cone parameters. For spotlights only, an additional set of parameterws is considered in lighting calculations, to pay attention to the cone angle of the spotlight beam and to the attenuation of light from the center of the light cone towards the light cones borders. Light is being attenuated with the cosine of the angle of light rays from the center of the cone beam raised by a number. The exponent is defining this exponential value. By default, the exponent is set to 0 i.e. distribution of light will not be attenuated within the cone beam at all. Valid values for exponent are in the range of [ ]. The cutoff angle defines the opening angle of the light cone measured from the central line of the light direction towards the border of the cone. Objects outside the light cone of a spotlight will not be considered for lighting calculations and will not receive any light from this light source. The initial value for the cutoff angle is 180.0, which means that no spot light at all, instead positional light spreading to all directions. Meaningful values for cutoff are [ ]. The function sets the local parameters of the specified light source object to the values passed by exponent and cutoff. light a pointer to a valid light source object exponent a floating point value for the exponent parameter cutoff a floating point value for the cutoff angle parameter 1 if function succeeded, otherwise 0 VRT_LightGetSpotParameters VRT_API int VRT_LightSetTargetNode (VRT_Light * light, VRT_Node * ntarget) Setting the target node of a directional light source object. In VRT, directional light sources can automatically track an object. By setting a target node to a directional light source object, VRT automatically calculates the light sources direction. Regardles wether the position of the light source is defined explicitely or by tracked with a position node, the direction is calculated from the lightâ s position towards the target node. The automatically calculated direction is overriding the explicitly set direction vector. This feature allows for easy animation of light direction in the case of directional light sources. Any movement of the target node will cause light to automatically follow. Direction tracking can be de-activated by setting NULL to the target node of a light source object. This function sets the local target_node parameters of the specified light source object to the node pased by the parameter ntarget. Whenever automatic direction tracking using target nodes shall be disabled, the function should be called with a NULL value for the ntarget parameter. light a pointer to a valid light source object ntarget a pointer to a valid node in the scene graph 10

15 1 if function succeeded, otherwise 0 VRT_LightGetTargetNode, VRT_LightSetDirection, VRT_LightGetDirection VRT_API int VRT_LightSetType (VRT_Light * light, int light_type) Setting the type of the specified light source object. VRT can handle three different types of light sources: VRT_LIGHT_DIRECTIONAL: Directional light is located a infinity and has a specific direction. It is a global light which is not attenuated over distance. VRT_LIGHT_POSITIONAL : Positional light has a dedicated puctual position in the scene and emitts light towards all directions from this point. Unlike directional light, positional light is a local light and can be attenuated with distance depending on its attenuation parameters. VRT_LIGHT_SPOT: Spotlights have both a specific location in the scene and sprread light towards a limited are around a specific direction. Spotlights are local lights and can be attenuated with distance depending on their attenuation parameters. The amount of light distribution around the main light direction can be controlled with the exponent and cutoff parameters of the spotlight object. The function sets the type of the specified light source object to the supplied value. Observe that light_type must be either one of the three predefined values: VRT_LIGHT_DIRECTIONAL VRT_LIGHT_POSITIONAL VRT_LIGHT_SPOT light a pointer to a light source object light_type a valid light type value 1 if function succeeded, otherwise 0 VRT_LightGetType, VRT_LightNew VRT_API int VRT_LightSwitchOff (VRT_Light * light) Switching off a light source object. In VRT lights can be switched on and off in order to flexibly allow for changes in illumination settings. The function switches off the specified light source. The light source will remain in the internal list of lights, but it will be ignored in the rendering process. Note: There can be at most MAX_GL_LIGHTS simultaneously activated light sources in the scene. The actual value depends on the OpenGL implementation; but it is usually 8. light a pointer to a light source object 1 if function succeeded, otherwise 0 VRT_LightGetSwitchState, VRT_LightSwitchOn VRT_API int VRT_LightSwitchOn (VRT_Light * light) Switching on a light source object. In VRT lights can be switched on and off in order to flexibly allow for changes in illumination settings. Note: There can be at most MAX_GL_LIGHTS simultaneously activated light sources in the scene. The actual value depends on the OpenGL implementation; but it is usually 8. The function switches on the specified light source. If after switching more than MAX_GL_LIGHTS are activated 11

16 at the same time, not all lights will actually be effective. In this situation, the order in which lights have been created determine wether or not a light is visible and not the order in which lights are switched on and off. In other words: The rank in the internal light list determines visibility. In practice, one should avoid to use many lights at the same time, since rendering performance is diminished dramatically for every new light activated source in the scene. light a pointer to a light source object 1 if function succeeded, otherwise 0 VRT_LightGetSwitchState, VRT_LightSwitchOff VRT_API void VRT_SetLightModel (int lightmodel) Setting the current light model. VRT can perform lighting calculations in two different ways. Global lightning (VRT_GLOBAL_LIGHT_MODEL) calculations, take care about the direction and position of lights in relation to the shaded objects surface attitude. In local lighting calculations (VRT_LOCAL_LIGHT_MODEL), in addition the relation between direction of light and direction from object towards the observer considered in illumination calculations. This gives more realistic shading results at the cost of decreased rendering performance. By default, VRT_GLOBAL_LIGHT_MODEL is installed and should only be changed, if specific illumination effects are desired. Lightmodel must be either one of the predefined values: VRT_GLOBAL_LIGHT_MODEL VRT_LOCAL_LIGHT_MODEL lightmodel the name of a VRT light model void VRT_GetLightModel System Functions VRT_API int VRT_GetLastError (char *error_message, int size) Get error code and error message for the last VRT error. VRT_API void VRT_Close () Close the VRT library. VRT_API void VRT_SimulationLoop () Start the VRT simulation loop. 12

17 VRT_API void VRT_ExitSimulationLoop () Leave the VRT simulation loop from any point within the user program. VRT_API void VRT_PrintSceneGraph () Prints the current scene graph to the VRT console. VRT_API float VRT_GetFrameRate () Get the current fram rate of VRT. VRT_API float VRT_GetSimulationTime () Get the up-time of the simulation. VRT_API void VRT_GetSystemTime (int *h, int *m, int *s) Get the systems current time from midnight. VRT_API void VRT_Init (int *argcp, char **argv, char *vrt_h_version, char *vrt_vnc_h_version) Initialize VRT. VRT_API VRT_Context * VRT_GetContext () Used to get the current VRT context. VRT_API void VRT_SetCallback (VRT_HookPtr hook) Register the VRT callback function. VRT_API int VRT_SetDisplay (int mode) Set the VRT display mode and create main window. VRT_API int VRT_SaveFrameToBitmap (char *filename) Copy a frame and save it to a bitmap file. VRT_API void VRT_PlaySound (char *filename) Plays a sound. VRT_API void VRT_FullScreen () requests that the current window be made full screen. VRT_API void VRT_ReshapeWindow (int width, int height) requests a change to the size of the current window. VRT_API void VRT_PositionWindow (int x, int y) requests a change to the position of the current window. VRT_API int VRT_GetModifiers () returns the modifier key state when certain callback messages were generated. 13

18 Function Documentation VRT_API void VRT_Close () Close the VRT library. This function is called to close the VRT library. It frees up any resources allocated by the system during run-time. This includes any nodes as well as geometries remaining in the scene graph. VRT_Init VRT_API void VRT_ExitSimulationLoop () Leave the VRT simulation loop from any point within the user program. This function can be used by the application programmer to terminate the simulation loop of VRT at any time of the simulation. After a call to this function, all actions defined within the user callback function will be finished. Upon return to the VRT simulation loop, the kernel will be cleaned up and terminate the system simulation loop without redrawing the scene. The user should issue an VRT_Close command after the call to VRT_SimulationLoop in the main program. VRT_SimulationLoop, VRT_Close VRT_API void VRT_FullScreen () requests that the current window be made full screen. VRT_FullScreen requests that the current window be made full screen. The exact semantics of what full screen means may vary by window system. The intent is to make the window as large as possible and disable any window decorations or borders added the window system. The window width and height are not guaranteed to be the same as the screen width and height, but that is the intent of making a window full screen. Subsequent VRT_ReshapeWindow and VRT_PositionWindow requests on the window will disable the full screen status of the window. VRT_ReshapeWindow, VRT_PositionWindow VRT_API VRT_Context* VRT_GetContext () Used to get the current VRT context. Wrapper function used to retrieve the global vrtctx pointer. 14

19 The current VRT context. VRT_API float VRT_GetFrameRate () Get the current fram rate of VRT. This function computes the current frame rate of VRT. The current frame rate. VRT_GetSimulationTime, VRT_GetSystemTime VRT_API int VRT_GetLastError (char * error_message, int size) Get error code and error message for the last VRT error. This function is used to retrieve the error code and error message corresponding to the most recently occured VRT error. It can be used to print error messages to a file. error_message a string to return the error message in size size of the string the error code for the last error VRT_API int VRT_GetModifiers () returns the modifier key state when certain callback messages were generated. VRT_GetModifiers returns the modifier key state at the time the input event for a keyboard, special, or mouse callback is generated. This routine may only be called while a keyboard, special, or mouse callback is being handled. The window system is permitted to intercept window system defined modifier key strokes or mouse buttons, in which case, no VRT callback message will be generated. This interception will be independent of use of VRT_GetModifiers. The bitmask components of the returned integer value are: VRT_ACTIVE_SHIFT Set if the Shift modifier or Caps Lock is active. VRT_ACTIVE_CTRL Set if the Ctrl modifier is active. VRT_ACTIVE_ALT Set if the Alt modifier is active. the modifier key state VRT_API float VRT_GetSimulationTime () Get the up-time of the simulation. This function returns the time elapsed since the simulation loop has been entered for the first time. The time returned is a floating point value indicating the elapsed time in seconds. Time elapsed since simulation start. 15

20 VRT_GetFrameRate, VRT_GetSystemTime VRT_API void VRT_GetSystemTime (int * h, int * m, int * s) Get the systems current time from midnight. This function returns the computer systems current time of the day. h pointer to hour m pointer to minute s pointer to second VRT_GetFrameRate VRT_API void VRT_Init (int * argcp, char ** argv, char * vrt_h_version, char * vrt_vnc_h_version) Initialize VRT. This function initializes VRT for use. All internal states along with the scene graph is set up. No other VRT functions should be called prior to a call to this function. argcp pointer to the program's unmodified argc variable from main. Upon return, the value pointed to by argcp will be updated, because VRT_Init extracts any command line options intended for the VRT library. argv The program's unmodified argv variable from main. Like argcp, the data for argv will be updated because VRT_Init extracts any command line options understood by the VRT library. VRT_Close VRT_API void VRT_PlaySound (char * filename) Plays a sound. This function loads the sound resource given by soundfile and plays the sound in asynchronous mode. VRT_PlaySound returns immediately to the calling process while the sound may be played in background. The format of the sound file must be Windows style wave format (.wav). filename filename including path to.wav file VRT_API void VRT_PositionWindow (int x, int y) requests a change to the position of the current window. VRT_PositionWindow requests a change in the position of the current window. The x and y parameters are pixel offsets from the screen origin. x New X location of window in pixels. y New Y location of window in pixels. 16

21 VRT_ReshapeWindow, VRT_FullScreen VRT_API void VRT_PrintSceneGraph () Prints the current scene graph to the VRT console. This function prints a text representation of the current scene graph to the VRT console window. VRT_POut VRT_API void VRT_ReshapeWindow (int width, int height) requests a change to the size of the current window. VRT_ReshapeWindow requests a change in the size of the current window. The width and height parameters are size extents in pixels. The width and height must be positive values. width New width of window in pixels. height New height of window in pixels. VRT_FullScreen, VRT_PositionWindow VRT_API int VRT_SaveFrameToBitmap (char * filename) Copy a frame and save it to a bitmap file. The function can be executed from within the simulation callback function to copy the frame buffer to a bitmap which is automatically stored into a Windows BMP file. filename a string containing a valid file name 1 on success 0 on failure VRT_CopyFrameToTexture, VRT_SaveTextureToBitmap VRT_API void VRT_SetCallback (VRT_HookPtr hook) Register the VRT callback function. This function registers the user-supplied VRT event handler callback function. The callback function prototype is defined as a pointer to a function which returns void and which accepts one parameter of type EventRef: typedef void (*VRT_HookPtr)(EventRef event); hook pointer to the callback function VRT_SimulationLoop 17

22 VRT_API int VRT_SetDisplay (int mode) Set the VRT display mode and create main window. This function sets the VRT display mode which can be mono, stereo, splitted stereo, virtual plane and mirrored, or a combination. It also creates and displays the VRT main window. mode display mode Zero on failure. VRT_API void VRT_SimulationLoop () Start the VRT simulation loop. This function starts the VRT simulation by entering a loop where it continously calls the registered callback function. The loop is exited only when the application is terminated. VRT_SetCallback Rendering Modules Texturing Pipe Shadow Functions VRT_API void VRT_SetClearColor (float r, float g, float b, float a) Sets the VRT clearing color. VRT_API void VRT_GetClearColor (float *r, float *g, float *b, float *a) Get the clearing color VRT uses. Function Documentation VRT_API void VRT_GetClearColor (float * r, float * g, float * b, float * a) Get the clearing color VRT uses. 18

23 This function gets the current clearing color being used by VRT. The color component ranges are 0-1 inclusive. r a pointer to the red component g a pointer to the green comonent b a pointer to the blue component a a pointer to the alpha component VRT_SetClearColor VRT_API void VRT_SetClearColor (float r, float g, float b, float a) Sets the VRT clearing color. This function sets the color that VRT uses to clear the main window when redrawing the screen. r color red component g color green component b color blue component a color alpha component VRT_GetClearColor Texturing Functions VRT_API void VRT_SetTextureModulationMode (int texture_modulation) Setting the global texture modulation mode. VRT_API int VRT_GetTextureModulationMode () Retrieving the currently set texture modulation mode. VRT_API VRT_Htx VRT_LoadTexture (char *filename) Load a texture from file. VRT_API VRT_Htx VRT_CreateRGBATexture (int sx, int sy, char *texels) Create a texture. VRT_API int VRT_DeleteTexture (VRT_Htx *texture) Delete a texture. VRT_API int VRT_ReplaceRGBATexture (VRT_Htx *texture, int sx, int sy, char *texels) Replace a texture. 19

24 VRT_API int VRT_ReplaceRGBASubTexture (VRT_Htx *texture, int x, int y, int w, int h, char *texels) Replaces part of a texture. VRT_API VRT_Htx VRT_CopyFrameToTexture () Render a frame to a texture. VRT_API int VRT_SaveTextureToBitmap (VRT_Htx *texture, char *filename) Save a texture into a file. Function Documentation VRT_API VRT_Htx VRT_CopyFrameToTexture () Render a frame to a texture. The function can be executed from within the simulation callback function to copy the frame buffer to a texture. A handle to a texture. VRT_SaveTextureToBitmap, VRT_SaveFrameToBitmap VRT_API VRT_Htx VRT_CreateRGBATexture (int sx, int sy, char * texels) Create a texture. This function creates a texture, given dimensions of the texture to be created and texel data. The texel data is a collection of color specifications on the RGBA form. That is, four values an the range of (char type) indicating the red, green, blue and alpha components of a color. The texel data is an array of <width*height> such tuples. Note: The current texture mode is affecting the type of texture created. sx width of the texture sy height of the texture texels pointer to an array of texel data A texture. VRT_LoadTexture, VRT_CreateRGBATexture, VRT_DeleteTexture, VRT_ReplaceRGBATexture, VRT_ReplaceRGBASubTexture, VRT_SetTextureModulationMode 20

25 VRT_API int VRT_DeleteTexture (VRT_Htx * texture) Delete a texture. This function deletes a texture. texture a texture A VRT error code VRT_LoadTexture, VRT_CreateRGBATexture, VRT_ReplaceRGBATexture, VRT_ReplaceRGBASubTexture VRT_API int VRT_GetTextureModulationMode () Retrieving the currently set texture modulation mode. The function returns the currently set texture modulation mode. The texture modulation mode is a environment state variable which affects the visual appearnace of textures. Whenever a texture is read from a file or created, the texture modulation mode at the time of texture creation determines how the texture will be created. Decal textures do generally replace the objects or polygons color with the picture contained in the texture. In modulate textures, the color and transparency of texels is multiplied with the color and transparency of the object and the rendered. As a result of this, the alpha channel in a texture can be used to modulate color and transparency of the entire object. In addition, in VRT a zero value texture element will not be rendered at all when a modulate texture is mapped upon a polygon. Therefore, textures can be used to stencil out irregular shapes from objects. VRT_TEXTURE_MODULATION_DECAL VRT_TEXTURE_MODULATION_MODULATE VRT_TEXTURE_MODULATION_BLEND VRT_SetTextureModulationMode, VRT_CreateRGBATexture, VRT_LoadTexture VRT_API VRT_Htx VRT_LoadTexture (char * filename) Load a texture from file. This function loads a texture form a Windows Bitmap (.BMP) file. The bitmap file must contain bitmap of uncompressed true color RGB format, otherwise, the function fails. In addition, the size of the texture is recommended to have a format of nkxnk. If the file identified by filename can not be opened or is not existing, the function will return NULL. Note: The current texture mode is affecting the type of texture created. filename name of texture file A handle to a texture. VRT_LoadOBJ, VRT_GeometrySavePLG, VRT_GeometrySaveVRML, VRT_LoadTexture, VRT_SetTextureModulationMode 21

26 VRT_API int VRT_ReplaceRGBASubTexture (VRT_Htx * texture, int x, int y, int w, int h, char * texels) Replaces part of a texture. This function inserts textels in a larger texture. The texel data is a collection of color specifications on the RGBA form. That is, four values an the range of (char type) indicating the red, green, blue and alpha components of a color. The texel data is an array of <w*h> such tuples. Note: The current texture mode is affecting the type of texture created. texture reference to the texure handle. x the number of horizontal texels from the lower left corner of texture to start replacing. y the number of vertical texels from the lower left corner of texture to start replacing. w the widht of the subtexture. h the heigth of the subtexure. texels preference to the raw subtexel data. A VRT error code. VRT_CreateRGBATexture, VRT_PolygonSetTexture, VRT_SetTextureModulationMode, VRT_ReplaceRGBATexture VRT_API int VRT_ReplaceRGBATexture (VRT_Htx * texture, int sx, int sy, char * texels) Replace a texture. This function replaces a texture by creating a new texture in place of an old one. The texel data is a collection of color specifications on the RGBA form. That is, four values an the range of (char type) indicating the red, green, blue and alpha components of a color. The texel data is an array of <width*height> such tuples. Note: The current texture mode is affecting the type of texture created. texture address of (pointer to) a texture handle sx width of texture sy height of texture texels pointer to texel raw data Zero on failure. VRT_CreateRGBATexture, VRT_PolygonSetTexture, VRT_SetTextureModulationMode, VRT_ReplaceRGBASubTexture VRT_API int VRT_SaveTextureToBitmap (VRT_Htx * texture, char * filename) Save a texture into a file. This function writes a textureidentified by texture into a file. The bitmap is stored as a uncompressed Windows bitmap with 24 bits of true color. If the filename/location is not valid the function returns an error. texture handle to a texture filename name of the file/location where to save the bitmap Zero on failure. 22

27 VRT_CopyFrameToTexture, VRT_SaveFrameToBitmap VRT_API void VRT_SetTextureModulationMode (int texture_modulation) Setting the global texture modulation mode. The function sets/changes the currently texture modulation mode. The texture modulation mode is a VRT environment state variable which affects the visual appearnace of textures. Whenever a texture is read from a file or created, the texture modulation mode at the time of texture creation determines how the texture will be created. Decal textures do generally replace the objects or polygons color with the picture contained in the texture. In modulate textures, the color and transparency of texels is multiplied with the color and transparency of the object and the rendered. As a result of this, the alpha channel in a texture can be used to modulate color and transparency of the entire object. In addition, in VRT a zero value texture element will not be rendered at all when a modulate texture is mapped upon a polygon. Therefore, textures can be used to stencil out irregular shapes from objects. Texture_modulation must be either on of the defined values: VRT_TEXTURE_MODULATION_DECAL VRT_TEXTURE_MODULATION_MODULATE VRT_TEXTURE_MODULATION_BLEND texture_modulation the name of a VRT texture modulation mode void VRT_GetTextureModulationMode, VRT_CreateRGBATexture, VRT_ReplaceRGBATexture, VRT_LoadTexture Intersections Detailed Description Intersection testing. Functions VRT_API int VRT_IntersectRayTriangleUVT (float *p, float *d, float *v1, float *v2, float *v3, float *uvt) Test for intersection of a ray with a triangle. VRT_API int VRT_IntersectRayTriangle (float *p, float *d, float *v1, float *v2, float *v3, float *t) Test for intersection of a ray with a triangle. VRT_API int VRT_IntersectTriangleTriangle (float *v1, float *v2, float *v3, float *u1, float *u2, float *u3) Test for triangle-triangle intersection. 23

28 VRT_API int VRT_IntersectRayQuad (float *p, float *d, float *v1, float *v2, float *v3, float *v4, float *t) Test for intersection of a ray with a four sided polygon. VRT_API int VRT_IntersectRayNode (float *p, float *d, VRT_Node *anode, float *t, VRT_HPlg *hit_poly) Test for intersection of a ray with a node. VRT_API int VRT_NodeIntersectNode (VRT_Node *sn, VRT_Node *tn) Check if two nodes intersect. Function Documentation VRT_API int VRT_IntersectRayNode (float * p, float * d, VRT_Node * anode, float * t, VRT_HPlg * hit_poly) Test for intersection of a ray with a node. This function test whether the ray defined by starting point p and directional vector d is intersecting with the given nodes geometry. This function is one of the most convenient procedures to test for rayobject intersection. This function performs in a three stage procedure in order to improve runtime performance. Observe, that intersection testing is performed for the geometry of the given node with regard to the current attitude of the node specified by the nodes current transformation matrix. Therefore, the rays coordinates are specified in world coordinates, and, if intersection testing is positive, the resulting intersection point is considered in world coordinates. Note that only the nodes geometry is considered for testing and not the children of the node. In case of intersection, the variable t gives the distance of the intersection point i from p along the direction vector d. Hence, the world coordinates of the point of intersection i can be calculated as follows: i = p + t*d. p a pointer to ray starting coordinates d a pointer to ray direction vector components anode a pointer to the node to be tested t a pointer to the distance of the intersection point hit_poly a pointer to the hit polygon. Zero, if test fails. Non-zero, if ray intersects with nodes geometry. VRT_IntersectRayTriangleUVT, VRT_IntersectRayTriangle, VRT_IntersectRayQuad, VRT_NodeIntersectNode VRT_API int VRT_IntersectRayQuad (float * p, float * d, float * v1, float * v2, float * v3, float * v4, float * t) Test for intersection of a ray with a four sided polygon. This function tests for intersection of a ray with a quadriliteral polygon. The ray is defined by starting point p and a directional vector d. The quadriliteral polygon is given by four vertices v1, v2, v3, and v4 respectively. If the ray intersects with the polygon, the function returns a non zero value. In that 24