Section 6 - Handling RAYZ Preferences

The RAYZ API allows you to:

Types of Preferences

There are two preference groups: User Interface and Project.

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.

Retrieving Existing Preference Values

There is a set of cpi calls to get preference values, depending on their type. These are all defined in CPI_Preferences.h. They all take the general form of
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
"/Node Defaults/Default Bit Depth", where is the project name, such as "project1".

To look up the value of the Default Full Size, the path would be
"/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 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):


#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.

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 )

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 "" or "User Inteface/". You can browse the Preferences editor to discover the full path name to any given preference.

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.2/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 );

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 "/" or "User Interface/". For example, to create a set of Project preferences associated with color spaces, you would do something like this:
     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.

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:

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:

Flag
Meaning
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

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.


[Previous Page] [Next Page]
[Table of Contents] [Index]

Copyright © 2002 Silicon Grail Inc.
736 Seward Street, Hollywood, CA 90038