FreeVR: Virtual Reality Integration Library
FreeVR
Tutorials
User Guide
Programming
Functions

FreeVR

TUTORIALS

DOWNLOADS

GUIDES
    Administrator
    User
    Programming
    Function List
    Library Dev
    Socket Interface

MAN PAGES


All materials
Copyright © 2024
William R. Sherman

Manpage of INTRO

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 2024, 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: 21:57:57 GMT, March 04, 2024