2.6. Configuration Files and Environment Variables

Open Inventor has a configuration database that stores information about the Open Inventor “environment.” The SoPreferences SoPreferences SoPreferences class handles the setting and querying of these configuration parameters.

Basics

The SoPreferences SoPreferences SoPreferences class manages a list of configuration parameters and their values. There are several ways that values are set into this list:

  • read from an Open Inventor configuration file

  • set using SoPreferences::set() methods

  • read from the system environment (e.g., using setenv (Unix) or set (Windows))

The SoPreferences SoPreferences SoPreferences configuration mechanism is not restricted to Open Inventor parameters. Applications are welcome to use it for their own parameters if appropriate.

Configuration Files

When Open Inventor is initialized, two configuration files are automatically read (if available):

  • a system configuration file $OIVHOME/ oiv.cfg or the file pointed to by the OIV_CONFIG_FILE environment variable, and

  • a local configuration file located in the application’s current working directory and named oiv.cfg.

Additional configuration files can be read using SoPreferences::readFile .

If a variable defined in the configuration file is already defined in the Open Inventor environment, the value in the configuration file overwrites the value currently in the environment.

If environment variable OIV_DEBUG_CONFIG is set, the files read and the values set are displayed to help debugging.

  • The values read from a configuration file are set in the Open Inventor configuration database. As these values are set only in memory, they are local to the application process and can only be retrieved using SoPreferences::getValue (or an equivalent method).

A configuration file can be very handy, for example, when you are running your application from the VC++ IDE on Windows. Prior to Open Inventor 4.0, if you wanted to experiment with various environment variable settings, you had to exit and restart VC++ every time you changed a setting in the system environment. Now you can simply edit the values in your configuration file, then rerun your application. The new settings in the config file will be used.

“set” Methods

The SoPreferences SoPreferences SoPreferences class has many “ set ” methods that you can use to set an individual configuration parameter in the Open Inventor environment. The setValue() method can be used for setting any parameter value. Internally, the character string value is parsed into a value of the appropriate type. The other methods (setBool(), setInt(), etc.) are used for setting a parameter value of a particular type.

The SoPreferences SoPreferences SoPreferences class has many “ set ” methods that you can use to set an individual configuration parameter in the Open Inventor environment. The SetValue() method can be used for setting any parameter value. Internally, the character string value is parsed into a value of the appropriate type. The other methods (SetBool(), SetInt(), etc.) are used for setting a parameter value of a particular type.

The SoPreferences SoPreferences SoPreferences class has a “ set ” method that you can use to set an individual configuration parameter in the Open Inventor environment. The setValue() method can be used for setting any parameter value. Internally, the character string value is parsed into a value of the appropriate type.

void setValue (const char *name, const char *value=NULL);
void setBool (const char *name, bool value);
void setInt (const char *name, int value);
void setLong (const char *name, long value);
void setFloat (const char *name, float value);
void setDouble (const char *name, double value);
void setString (const char *name, const SbString &value);
void setVec3f (const char *name, const SbVec3f &value);
void setColor (const char *name, const SbColor &value);
void setVec2s (const char *name, const SbVec2s &value);
      
void SetValue (string name, string value);
void SetBool (string name, bool value);
void SetInt (string name, int value);
void SetLong (string name, int value);
void SetFloat (string name, float value);
void SetDouble (string name, double value);
void SetString (string name, string value);
void SetVec3f (string name, SbVec3f value);
void SetColor (string name, SbColor value);
void SetVec2s (string name, SbVec2s value);
      
SoPreferences.setValue(String key, String value);
           

These methods set a configuration parameter in the Open Inventor configuration database. As this value is set only in memory, it is local to the application process and can only be retrieved using SoPreferences::getValue() (or an equivalent method).

These methods set a configuration parameter in the Open Inventor configuration database. As this value is set only in memory, it is local to the application process and can only be retrieved using SoPreferences.GetValue() (or an equivalent method).

This method sets a configuration parameter in the Open Inventor configuration database. As this value is set only in memory, it is local to the application process and can only be retrieved using SoPreferences.getValue() (or an equivalent method).

Note that by prepending a “-” to the variable name it is possible to unset it in the configuration database.

System Environment Variables

Configuration parameters can also be set using system environment variables. For example, on Unix systems, the setenv/export command can be used to set environment variables and their values. On Windows, the set command can be used in a Command Prompt, or values can be set via the Control Panel.

A possible disadvantage of using system environment variables is that you have to be aware of the scope of their influence (which windows or applications are affected, when, and for how long). The configuration file and the “ set ” methods described above are platform independent, so you don’t need to know this. The system environment may have limited size on some systems. It is much easier to edit an Open Inventor configuration file than to type and re-type variable names on the command line.

File Format

White space (blank, tab) is used to separate the variable name from its value. Each line can contain only one definition.

# comment
# NAME1, NAME2, and NAME3 are defined and associated
# with value1, value2, and value3 respectively.
NAME1 value1
NAME2 value2 # comment
+NAME3 value3

# NAME4 and NAME5 are defined and no values are associated
# with these NAMEs.
NAME4
+NAME5 # comment

# If NAME6 is defined in the system environment or in one
# of the previously loaded config files, it is now undefined.
-NAME6 # comment

Note that by prepending a “-” to the variable name it is possible to unset it in the configuration database.

Sample Configuration File

# Sets up the initial state of a viewer
# Red/cyan stereo viewing active
OIV_STEREO_ACTIVE 1
OIV_STEREO_TYPE ANAGLYPH_RED_CYAN
OIV_STEREO_OFFSET .12
OIV_STEREO_BALANCE -.5

Querying the Configuration Database

To query the value of a configuration parameter, the SoPreferences SoPreferences SoPreferences class provides convenience methods which convert values from string to integer, float, or vector. First, the value is searched for in the configuration database, and if not found, is searched for in the system environment. If the value is found only in the system environment, it is stored in the configuration database for faster access the next time it’s queried.

The basic method is SoPreferences::getValue()SoPreferences.GetValue()SoPreferences.getValue(), which takes a parameter name and returns the string associated with it (NULL if the parameter is not found). For example:

const char *oivhome = SoPreferences::getValue("OIVHOME");
     
string oivNetHome = SoPreferences.GetValue("OIVNETHOME");
     
String oivJHome = SoPreferences.getValue("OIVJHOME");
     

However, for most parameters the application would have to check for a NULL return and either convert the string to some other data type (for example, int) or set a default value. SoPreferences SoPreferences SoPreferences provides convenience methods that encapsulate this common pattern:

bool getBool (const char *name, bool defaultValue);
int getInt (const char *name, int defaultValue);
long getLong (const char *name, long defaultValue);
float getFloat (const char *name, float defaultValue);
double getDouble (const char *name, double defaultValue);
const SbString &getString (const char *name, const SbString &defaultValue);
const SbVec3f &getVec3f (const char *name, const SbVec3f &defaultValue);
const SbColor &getColor (const char *name, const SbColor &defaultValue);
const SbVec2s &getVec2s (const char *name, const SbVec2s &defaultValue);
     
bool GetBool (string name, bool defaultValue);
int GetInt (string name, int defaultValue);
float GetFloat (string name, float defaultValue);
double GetDouble (string name, double defaultValue);
string GetValue (string name);
string GetString (string name, string defaultValue);
SbVec3f GetVec3f (string name, SbVec3f defaultValue);
SbColor GetColor (string name, SbColor defaultValue);
SbVec2s GetVec2s (string name, SbVec2s defaultValue);
     
boolean getBoolean (String key, boolean defaultValue);
int getInteger (String key, int defaultValue);
long getLong (String key, long defaultValue);
float getFloat (String key, float defaultValue);
double getDouble (String key, double defaultValue);
String getValue (String key);
String getValue (String key, String defaultValue);
     

Each one takes a parameter name and a default value and returns either the appropriate conversion of the parameter value or the default value. For example:

const SbColor bkgrd =
SoPreferences::getColor("OIV_BACKGROUND_COLOR",SbColor(.5,.5,.5));
     
SbColor bkgrd =
SoPreferences.GetColor("OIV_BACKGROUND_COLOR", new SbColor(.5f,.5f,.5f));
     
boolean valid =
SoPreferences.getBoolean("OIV_VALID", true);
     

Configuring Open Inventor’s Initial State

Open Inventor 4.0 added many new configuration parameters that make it easy to pre-configure Open Inventor to a desired initial state. (See SoPreferences SoPreferences SoPreferences for the complete list.) This can be useful to quickly experiment with how different settings affect performance, to set defaults for simple programs (e.g., demos) that do not have their own configuration file, etc. There are two general categories:

  • Variables that affect the initial viewer or render action state. These are, of course, overridden by settings made in the application code. For example:

  • OIV_TRANSPARENCY_TYPE specifies the default transparency type (which is normally SCREEN_DOOR).

    Equivalent to calling SoGLRenderAction::setTransparencyType().

  • OIV_BACKGROUND_COLOR specifies the initial background color.

    Equivalent to calling SoXtRenderArea::setBackgroundColor().

  • Variables that affect the initial traversal state (this is the state modified by nodes during traversal). These are, of course, overridden by the nodes in the scene graph. For example:

  • OIV_COMPLEXITY specifies the default complexity value (which is normally 0.5). Equivalent to putting an SoComplexity SoComplexity SoComplexity node at the top of the scene graph and setting its value field.

  • OIV_TEXTURE_QUALITY specifies the default texture quality value (which is normally 0.5). Equivalent to putting an SoComplexity SoComplexity SoComplexity node at the top of the scene graph and setting its textureQuality field.