INTRO
Section: FreeVR Functions (3fv)
Updated: 27 November 2013
Index
Return to Main Contents
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
The reference manual divides the functions by category, with an alphabetical
listing at the end.
NOTES
FreeVR Function Naming Scheme
As an aid for the FreeVR programmer to more rapidly determine what a
function does, or make an educated guess for the name of a desired function,
FreeVR has adopted a function naming scheme for which all functions
should follow.
Unfortunately, some of the naming rules conflict with one another, and in
these cases a precedence determination is made for each individual function.
-
- •
-
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
The rules for FreeVR type names are similar to the function scheme.
Of course, types are much simpler, so generally consist only of the
"vr" prefix, and then a name that begins with an upper case letter.
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
The FreeVR API functions can be divided into these general categories
of related operations:
-
• 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 2021, Bill Sherman, All rights reserved.
Index
- NAME
-
- DESCRIPTION
-
- NOTES
-
- FreeVR Function Naming Scheme
-
- FreeVR Types
-
- FreeVR API Function Categories
-
- SEE ALSO
-
- COPYRIGHT
-
This document was created by
man2html,
using the manual pages.
Time: 18:37:43 GMT, May 02, 2021