INTRO

NAME

intro — Introduction to the FreeVR API functions  

DESCRIPTION

Section 3 of the FreeVR manual describes all library functions, macros and data structures useful for writing virtual reality experiences. (I.e. it does not include functions internal to the library.)

Presently, the API manpages have not yet been created. However, all the API functions are adequately described in the "FreeVR Function Reference Manual" available on the FreeVR webpage:

http://freevr.org/functions.html

NOTES

FreeVR Function Naming Scheme

•

All functions (and types) begin with "vr" — no exceptions.

•

All Performer related functions begin with "vrPf".

•

All identifying features of the function are included as part of the name.

•

Each word that identifies a feature begins with an upper case letter, and is followed by lower case letters.

•

Acronyms that identify a feature are capitalized throughout (eg. RW for "real world").

•

Functions related to a common utility or operation will begin their name with a word or words to describe this common base. Examples include the vrUserTravel...(), vrRender...(), vrShmem...(), and vrGet...() suites of functions. There are some exceptions caused by precedence of the final rule.

•

A group of functions with similar operations will include the types of arguments as part of the name. These function names will include references to each argument, appearing in the same left to right order. For example, there are many functions to set the value of a 4x4 matrix, all of the form vrMatrixSet...(), differing in what is being set and the type of values give. So, the translation of a vrMatrix can be set with either three double precision floats, or an array of doubles:
  vrMatrixSetTranslation3d() or vrMatrixSetTranslationAd().

•

In cases where the first argument is actually used as a memory placeholder for the return value, then the argument type will appear immediately after the initial "vr". This is generally the case for "Get" and math functions that return multivalue-types such as vrMatrix, vrPoint and vrVector. This rule generally takes precedence over the previous two rules.

FreeVR Types

FreeVR types are defined generally for multi-valued collections of data, such as a 4x4 Homogeneous matrix used for graphics operations — vrMatrix. For functions that return single values (such as the value of a button or valuator), a basic int or double type is used. Many of the FreeVR types store all the values as a single array of doubles in field "v".

Common types used in VR applications include:

•

vrMatrix — 16 doubles stored as array "v", in row-column order to match the OpenGL matrix format.

•

vrPoint — 3 doubles stored in array "v", referred to as VR_X, VR_Y, and VR_Z.

•

vrVector — 3 doubles stored in array "v", referred to as VR_X, VR_Y, and VR_Z.

•

vrQuat — 4 doubles stored as array "v", in vector/scalar order (i, j, k, scalar) referred to as VR_X, VR_Y, VR_Z, and VR_W.

•

vrEuler — two arrays of 3 doubles for translational ("t" field) and rotational ("r" field) components, referred to respectively as VR_X, VR_Y, VR_Z; and VR_AZIM, VR_ELEV, VR_ROLL.

NOTE: Because the types vrPoint and vrVector have the same internal representation, one can be converted to the other through a simple type-cast. However, there is a good reason why both types exist. And that reason is that mathematically speaking, they are different quantities. The difference basically amounts to how each 3-quantity array is extended when converted to a 4-quanity entity that will be multiplied by a 4x4 homogeneous matrix — a point has a "1" as the fourth value, while a vector has a "0".

NOTE: The use of vrEuler is not recommended. This type and related functions are provided only as a convenience for porting applications originally written with libraries that make use of Euler angles. There is one exception to this rule, and that is in the use of the billboarding functions (vrRenderGetBillboardAngles3d() & vrRenderGetBillboardAnglesAd()). In these cases, the relationship between the user and some location in space is returned as Euler angles which can be formulaicly fed into OpenGL calls to rotate objects to face the user.

Along with the above types, FreeVR defines some "macro" values for accessing type subelements in a clear way. These are:

• VR_X — the x component of a "v" field ("t" field of vrEuler)
• VR_Y — the y component of a "v" field ("t" field of vrEuler)
• VR_Z — the z component of a "v" field ("t" field of vrEuler)
• VR_W — the w component of a "v" field of a quaternion
• VR_AZIM — the azimuth component of a vrEuler "r" field
• VR_ELEV — the elevation component of a vrEuler "r" field
• VR_ROLL — the roll component of a vrEuler "r" field

FreeVR API Function Categories

• System Operation
• Reading Inputs
• Controlling the Rendering
• Math Operations
• Special Math Functions for Converting Between VW & RW
• User Travel
• Debugging and Printing Functions
• Locking Operations
• Barrier Operations
• Special Functions for using the Performer library

SEE ALSO

intro(1fv), freevr(7fv)

Additional documentation is available at the FreeVR web site:

http://www.freevr.org

COPYRIGHT

Copyright 2024, Bill Sherman, All rights reserved.

Index

NAME

DESCRIPTION

NOTES

FreeVR Function Naming Scheme

FreeVR Types

FreeVR API Function Categories

SEE ALSO

COPYRIGHT