The User Interface settings, on the other hand, retain their value between RAYZ sessions, and are saved on disk. These are found in ~/.rayz/rayz2.0/Preferences/Defaults.pref
cpiGetPreference<type>( <type> *pointer, const char *prefPath)for example,
cpiGetPreferenceInt( CPI_Int32 *ival, const char *prefPath)The prefPath is a string which defines the path to the preference. The path will begin with either "Project/", if it is a Project preference, or "User Interface/", if it is a general Interface preference.
You can discover the complete path to a specific preference by looking in the
Preferences editor in RAYZ. For example, if you open the Project Settings
dialog, and go into the Settings folder, you will see a list of
Default preferences; one of these is Default Bit Depth. So the path
to this preference is
"Project/Node Defaults/Default Bit Depth".
To look up the value of the Default Full Size, the path would be
"Project/Settings/Default Full Size X".
Notice that the path is a
series of strings which are separated by '/' (forward slash) characters,
that spaces are allowed, and that there is no leading '/'.
There is an example of this in the Checker.C node plugin example. This
plugin looks up the default full size and uses that to set the default
image size in its parameters. To do this, the
CheckerInit() function contains the following lines of code:
#define XFULLSIZE_PATH "Project/Settings/Default Full Size X" #define YFULLSIZE_PATH "Project/Settings/Default Full Size Y" ... // use preferences to get default size to use CPI_Int32 xsize, ysize; if ( !cpiGetPreferenceInt( &xsize, XFULLSIZE_PATH ) ) { cpiError( "Couldn't get X size" ); return CPI_FALSE; } if ( !cpiGetPreferenceInt( &ysize, YFULLSIZE_PATH ) ) { cpiError( "Couldn't get Y size" ); return CPI_FALSE; }To retreive UI preferences, such as the Outside Image Color (the color of the image viewer outside the current image), the path always begins with "User Interface/". The full path to retreive this particular setting would be "User Interface/Settings/Image Viewer/Outside Image Color". Again, you can browse the Preferences Editor for the full path name to any preference.
There is a separate routine for each type of preference; these are
CPI_Bool cpiGetPreferenceInt( CPI_Int32 *val, const char *prefPath ) CPI_Bool cpiGetPreferenceFloat( CPI_Float32 *val, const char *prefPath ) CPI_Bool cpiGetPreferenceBool( CPI_Bool *val, const char *prefPath ) CPI_Bool cpiGetPreferenceColor( CPI_Float32 *redVal, CPI_Float32 *greenVal, CPI_Float32 *blueVal, const char *prefPath ) CPI_Bool cpiGetPreferenceString( char *tmpbuf, CPI_Uint32 bufSize, const char *prefPath ) CPI_Bool cpiGetPreferenceFile( char *fileId, CPI_Uint32 fileIdBufSize, char *fileMgr, CPI_Uint32 fileMgrBufSize, const char *prefPath )
As an example, the node plugin Preferences.C takes a color value from the user and uses it to set the Outside Image Color for the image viewer. The relevant lines of code are:
#define OUTSIDE_COLOR \ "User Interface/Settings/Image Viewer/Outside Image Color" ... // get the user's color choice from the color widget, // then set it into the Outside Image preference CPI_Float32 red, green, blue; cpiGetFloat( &red, "color.red", myTime ); cpiGetFloat( &green, "color.green", myTime ); cpiGetFloat( &blue, "color.blue", myTime ); cpiSetPreferenceColor( OUTSIDE_COLOR, red, green, blue );If you compile and run this plugin, you can see that as you change the color in the color chooser, the portion of the image viewer that is normally black is changed to the color you select. The rest of the plugin simply passes its input to its output.
Notice that the result of changing the preference is persistent; that is, the next time you run RAYZ, the last color you chose will again be used as the Outside Image Color. This is because the User Interface values are stored in your home directory in the .rayz directory, in the file .rayz/2.0/Preferences/Defaults.pref
Again, there is a separate routine for each type of preference you want to update. These are listed here.
void cpiSetPreferenceString( const char *prefPath, const char *prefStr ); void cpiSetPreferenceInt( const char *prefPath, CPI_Int32 val ); void cpiSetPreferenceFloat( const char *prefPath, CPI_Float32 val ); void cpiSetPreferenceBool( const char *prefPath, CPI_Bool val ); void cpiSetPreferenceColor( const char *prefPath, CPI_Float32 redVal, CPI_Float32 greenVal, CPI_Float32 blueVal ); void cpiSetPreferenceFile( const char *prefPath, const char *fileID, const char *fileMgr );
cpiAddPreferenceGroup( "Project/Color Space" );The second function adds preference values to this group. The function is defined like this:
void cpiAddPreferenceValue( const char *prefGroup, const char *prefName, const char *prefDescription, const char *defPrefVal, CPI_Int32 prefType, CPI_Int32 prefUIType );As an example, a call might look like this:
cpiAddPreferenceValue( "Project/Color Space", "Name", "Which color space to use", "RGB", CPI_PREF_STRING, CPI_PREF_UI_DEFAULT );The prefGroup parameter will be the same string that you passed to cpiAddPreferenceGroup(), while prefName will be a single preference within that new group. The prefDescription string is a user help string that will appear in the status line/popup help box.
defPrefVal is the value, in string form, of the default value(s) for this preference. Although you can set and get preferences as their native types (eg, float), these are all stored as strings and you must supply the default value that way.
Finally, the two flags are supplied. The prefType can be one of the following:
|
|
CPI_PREF_UI_DEFAULT | No restrictions on file searches |
CPI_PREF_UI_FILE_DIR_ONLY | Restricts the file browser in the Preferences Editor to searching for directories only |
CPI_PREF_UI_LOCAL_ONLY | Restricts the file browser to searching only for files on the local filesystem |
CPI_PREF_UI_LOCAL_DIR_ONLY | Restricts the file browser to searching only for directories on the local filesystem |
The Preferences.C node plugin example shows the creation of a custom preference. The creation is done once, in the Init() function. Because the init function of a node type is run once at load time, even if that type of node is never dropped onto the worksheet, the preference is created. If you compile and install this example, then run RAYZ, you will notice immediately after startup that there is a new preference category in the Project Settings dialog, called Color Space. This contains a single entry, Name, which defaults to the string RGB.
If you save the RAYZ session, and examine the .rayz file, you'll notice that this preference is not saved in it. That is because the value is still at the default (RGB) and so there is nothing to save. However, if you select this new preference, and change its value to "YIQ" (without quotes), and then save the session, the file will contain the preference and its new value.