User Interface settings retain their value between RAYZ sessions, and are saved on disk. These are found in ~/.rayz/rayz2.2/Preferences/Defaults.pref
Project settings, on the other hand, are associated with a specific RAYZ file, and are saved in that .rayz file (as with all RAYZ parameters, they are only saved if they are different from the default values).
Because RAYZ can load one .rayz file into another, via the FileGroup node, it is important to keep these preferences local to each project. That is, you don't want to include a new .rayz file, only to have that file's preferences modify the current project's preferences.
In order to cope with this, all currently active projects have a unique name. The name is of the form project1, project2, etc. This name is used to keep the different sets of preferences distinct. The function call cpiGetProjectName() can be used to find the name of the current project, and thus to access the appropriate set of preferences. There is an example of this in the next section.
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 "projectN/", where N is 1, 2, 3, etc, 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
To look up the value of the Default Full Size, the path would be
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 Checker source defines
a function for CreateInstance(), which is called when each new instance
of the node is created. We must use this function because at the time
that Init() is called, the project name is not known. So the code
looks like this (error checking is omitted for clarity):
There is a separate routine for each type of preference; these are
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:
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.2/Preferences/Defaults.pref
Again, there is a separate routine for each type of preference you want
to update. These are listed here.
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:
Note that "project1" is used here for clarity - in real life, you would
want to construct a path name using the the current name,
which is not guaranteed to be "project1".
The Preferences.C node plugin example shows this being done.
The mechanism for this is as follows:
If you compile and install Preferences.C, 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.
"
"
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 '/'.
#define XFULLSIZE_PATH "/Settings/Default Full Size X"
#define YFULLSIZE_PATH "/Settings/Default Full Size Y"
static CPI_PrivateData
CheckerInstance( void )
{
const char *projname;
char fullPath[64];
CPI_Int32 xsize, ysize;
// get the name of the current project
projname = cpiGetProjectName();
// now create the paths to the preferences we want
strcpy( fullPath, projname );
strcat( fullPath, XFULLSIZE_PATH );
cpiGetPreferenceInt( &xsize, fullPath );
strcpy( fullPath, projname );
strcat( fullPath, YFULLSIZE_PATH );
cpiGetPreferenceInt( &ysize, fullPath );
// finally, set these sizes into the GUI widgets as the new
// defaults for this instance of this node. The CPI_FALSE
// flag says that the user did not change this value, the
// software did
cpiSetInteger( xsize, "size.w", 1.0F, CPI_FALSE );
cpiSetInteger( ysize, "size.h", 1.0F, CPI_FALSE );
return NULL;
}
To retreive User Interface 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 retrieve 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.
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 )
Setting Preference Values
There is an equivalent set of function calls for setting the values of
preferences which are built into RAYZ. As before, the path name to the
variable must begin with either "
#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.
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 );
Creating Custom Preferences
You can create your own preferences, which users can then use, with
a pair of functions. The first, cpiAddPreferenceGroup(), creates a
category for your preference. This category (group) must be a subgroup
of either "
cpiAddPreferenceGroup( "project1/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( "project1/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.
The prefUIType only has meaning if the previous type is CPI_PREF_FILE; that
is, the prefUIType is a modifier of file preferences only.
This flag can be one of four values:
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
736 Seward Street, Hollywood, CA 90038