Customizing Shake

 

Summary

Setting Preferences and Customizing Shake

This chapter explains how to customize the appearance of Shake, macro interactivity, and performance parameters. It also lists environment variables you can set to improve Shake’s performance.

For information on creating Viewer scripts, see “Viewer Lookups, Viewer Scripts, and the Viewer DOD” on page 30 of the Shake 3 Reference Guide.

For information on creating custom kernels for filters, see “Convolve” on page 586 of the Shake 3 Reference Guide.

For a tutorial on creating a macro, see the “Making a Macro” lesson in the Shake 3 Tutorials.

Locations for .h Files and Custom Icons

This section discusses where to store files used to customize Shake.

Preference Files Search Path

Shake uses two important files in the <ShakeInstall>/Contents/Resources (<ShakeDir>/include for non-MacOS) directory, named nreal.h and nrui.h. The first file, nreal.h, lists every function and all default performance settings. This file should not be touched by the user, but may be read as a formatting reference. The commands found in this file can be copied and placed in your own startup Directory (see below). The second file, nrui.h, contains the information to build the interface. It assigns menu names and members, tabs, buttons, slider settings, and all of the default settings when they are called up in the interface. The commands in this file can be copied and placed in your ui Directory. As with the nreal.h file, you should not modify the nrui.h file. Create your own preference files (.h files) to either add to or change Shake’s performance.

Note: On Mac OS X, Ctrl-click or Right-click the Shake icon and choose Show Package Contents from the shortcut menu to view the Shake package contents (includes the nreal.h and nrui.h files).

To add your own files, create the following directory subtree:

<somewhere>/include/startup/ui

"Somewhere" can be one or more of three possible locations (read by Shake in the order listed below):

Setttings that change performance or add macros (see below) are located in <somewhere>/include/startup, and have a .h file extension, for example:

/Users/me/nreal/include/startup/memory_settings.h

This is refered to as the startup directory. Files in this locations are refered to as startup .h files.

Settings that change the interface in some way (see below) are usually located in <somewhere>/include/startup/ui, and have a .h file extension, for example:

/Users/me/nreal/include/startup/ui/slider_settings.h

This is referred to as the ui directory or sometimes startup/ui directory. Files inside it are referred to as ui .h files

Files that change additional default settings or add extra controls are in the templates directory, which is always under a ui directory:

/Users/me/nreal/include/startup/ui/templates/defaultfilter.h

All of these files can have any name, except “nreal.h” or “nrui.h,” which are reserved files used by Shake as the standard list of functions and settings. Also, they must have the .h extension, so a fast way to disable a file is to remove the extension.

Within a startup or startup/ui directory, files are loaded in no specific order. If it is important that a file is loaded before another file, this can be accomplished by one of the following:

Include files are never loaded twice, so it is okay if two .h files contain the same #include <somefile.h> statement.

If these files do not appear to be working, refer to the following checklist:

Icons Search Path

Just as you can create preference files, you can create your own icons. The description of the actual icons can be found in the section, “Using the Alternative Icons,” below. Icons can be found in one of three locations:

General Settings

The // (forward slashes) indicate that line is commented out and inactive.

Color Settings

Setting Tab Colors

In the ui directory:

 
nuiPushToolBox("Image");
nuiSetObjectColor("ImageToolBox", 
  tabRed, tabGreen, tabBlue, 
  textRed, textGreen, textBlue);
nuiPopToolBox();

This is an excerpt from the include/nrui.h file. The Image tab is opened and assigned a color for both the tab and the text on the tab. Instead of numbers for the color values, variables are used here to indicate the parameter. Search for the variable names above or enter your own explicit values. Doing this does not automatically assign color to nodes within the tab.

Setting Colors for the Nodes in the Node View

In the ui directory: 

nuiSetMultipleObjectsColor(
    nodeRed, nodeGreen, nodeBlue,
    textRed, textGreen, textBlue,

    "DisplaceX",	
    "IDisplace",	
    "PinCushion",	
    "Randomize",	
    "Turbulate",	
    "Twirl",		
    "WarpX"
);

This command assigns colors to nodes in the Node View. The nodeRed, green, etc., and textRed, green, etc., are supposed to be float values. When coloring the nodes, keep in mind that the default artwork is a medium gray, so you can have numbers above 1 for the node color parameters to multiply it up.

Setting Colors for the Time Bar

In the ui directory: 

gui.color.timeSliderTop = 0x373737FF;
gui.color.timeSliderBottom = 0x4B4B4BFF;
gui.color.timeSliderFocus = 0x5B5B5BFF;
gui.color.timeSliderText = 0x0A0A0AFF;
gui.color.timeSliderTextFocus = 0x000000FF; 
gui.color.timeSliderRange = 0x373737FF;
gui.color.timeSliderRangeReversed = 0x505037FF;
gui.color.timeSliderRangeText = 0x0A0A0AFF;
gui.color.timeSliderLines = 0xFFFFFFFF;
gui.color.timeSliderCurrent = 0x00FF00FF;
gui.color.timeSliderMouseTime=0xACAC33FF;
gui.color.timeSliderMouseTimeKey=0xFCFC65FF;

These are just a few plugs to change the coloring of the text in all time-based windows, such as the Curve Editor, Time Bar, and so on. The numbers are, obviously, in hex just to make things more difficult. Ignore the 0x and the last FFs. Note you often have control over a basic color and its mouse-focused variation.

Setting Colors for Groups in the Node View

In the ui directory: 

nuiSetObjectColor(
  "Group", .75, .75, .75
);

This sets the color of collapsed groups. If you set them to 1, the group takes on the color set in the Group’s color setting: 

nuiSetObjectColor("Group", 1., 1., 1.);
Setting Colors for the Curves in the Editor

In the ui directory: 

gui.color.curveDef = 0x658a61;
gui.color.curveDefFoc = 0xcccc26;
gui.color.curveDefSel = 0xcccc26;
gui.color.curveDefFocSel = 0xffff26;
//Curves starting with 'r' or 'R'
gui.color.curveR = 0xa74044;
gui.color.curveRFoc = 0xff0000;
gui.color.curveRSel = 0xff0000;
gui.color.curveRFocSel = 0xff8888;
//Curves starting with 'g' or 'G'
gui.color.curveG = 0x8de48d;
gui.color.curveGFoc = 0x00ff00;
gui.color.curveGSel = 0x00ff00;
gui.color.curveGFocSel = 0xaaffaa;
//Curves starting with 'b' or 'B'
gui.color.curveB = 0x406bf7;
gui.color.curveBFoc = 0x1818ff;
gui.color.curveBSel = 0x1818ff;
gui.color.curveBFocSel = 0x8888ff;
//Curves starting with 'a' or 'A'
gui.color.curveA = 0x888888;
gui.color.curveAFoc = 0xbbbbbb;
gui.color.curveASel = 0xbbbbbb;
gui.color.curveAFocSel = 0xeeeeee;

There are really only four basic curve types, the normal curve (Def), the focused curve (DefFoc), the selected curve (DefSel) and the focused, selected curve (DefFocSel). You then also have additional controls over curves that start with the letters r, g, b, and a.

Setting Colors for Text

In the ui directory: 

gui.fontColor = 0xFFFFFF;
gui.textField.fontColor = 0xFFFFFF;
gui.textField.tempKeyBackClr = 0xFFFFFF;
//For Landscape-style layout:
gui.textField.valModClr = 0xFFFFFF;
gui.textField.setKeyClr = 0xFFFFFF;
gui.textField.expressionColor = 0xFFFFFF; 

//the color of text on an active tab
gui.tabber.activeTint.red = .9;
gui.tabber.activeTint.green = .9;
gui.tabber.activeTint.blue = .87;

//the color of text on an inactive tab
gui.tabber.tint.red = .65;
gui.tabber.tint.green = .65;
gui.tabber.tint.blue = .63;
This colors the text in hexadecimal. There is a series of expressions near the very end of the nrui.h file that allows you to put in normalized RGB values that are then fed into the hex number, but you can also determine your color using the Color Picker.

fontColor = the color of the actual parameter name, messages, and also of macros without declared coloring.
textfield.fontColor = the color of the values within the text field.
tempKeyBackClr = a warning color for values entered when not in autosave mode for animated parameters. The value is not saved until autokey is enabled.

Some text colors can also be interactively modified in the Global's settings. These are saved into <UserDir>/nreal/settings when you choose File > Save Interface Settings.

Setting Time View Colors

In the startup or ui directory: 

gui.color.timeViewBarStd = 0x737373;
gui.color.timeViewBarTop = 0x909090;
gui.color.timeViewBarBtm = 0x303030;
gui.color.timeViewBarCut = 0x101010;
gui.color.timeViewBarRpt = 0x5a5a5a;
gui.color.timeViewBarMir = 0x5a5a5a;
gui.color.timeViewBarFrz = 0x424242;
gui.color.timeViewBarBlk = 0x0;
gui.color.timeViewBarClpLine = 0x0;
gui.color.timeViewFontInOut = 0x111144;
gui.color.timeViewFontStEnd = 0x441111;
gui.color.timeViewFontStd = 0xFFFFFF;
gui.color.timeViewIgnLine = 0xFF0000;
gui.color.stripedRowColLight = 0x373737;
gui.color.stripedRowColDark = 0x474747;
gui.color.timeViewDarkStripe = 0x373737;
gui.color.timeViewLightStripe = 0x474747;

The BarCut, BarRpt, BarMir, BarFrz, and BarBlk refer to the repeat modes, so each one has a different color.

Creating a Custom Palette

In the ui directory: 

nuiSetColor(1,1,0,0);
nuiSetColor(2,1,0.5,0);
nuiSetColor(3,1,1,0);
etc

This assigns default colors to the palette icons, with the first number as the button number.

Format

Creating Custom Listings for the Format Pop-Up

In the startup directory:

 
DefFormatType(
  "string", 
  width, 
  height, 
  aspectRatio, 
  viewerAspectRatio, 
  framesPerSecond, 
  fieldRendering
);


DefFormatType(
  "Academy", 1828, 1556, 1,1,24,"24 FPS"
);

To set the default format choice whenever you launch Shake, you can use: 
script.format = "FormatName";

Automatically Assigning the Default Width and Height to a Parameter in a Macro

In either startup or ui (typically inside of a macro's parameter settings): 

image MyGenerator(
  int width=GetDefaultWidth(),
  int height=GetDefaultHeight(),
  float aspectRatio=GetDefaultAspect(),
  int bytes = GetDefaultBytes()
)
These four commands check the default global settings and return the value at the time of node creation; they are not dynamically linked. Therefore, if you change the default parameters, the node’s values do not change.

Setting Format Defaults

In the startup directory: 

script.defaultWidth = 720;
script.defaultHeight = 486;
script.defaultAspect = 1;
script.defaultBytes = 1;
script.format = "Full";

Using the script.format overrides the other settings—you either set the first four or the format settings, as shown above.

Setting Maximum Viewer Resolution in the Interface

In the ui directory: 

gui.viewer.maxWidth = 4096;
gui.viewer.maxHeight = 4096;

By default, Shake protects the user from test rendering an enormous image by limiting the resolution of the Viewer to 4K. If the user accidently puts a Zoom set to 200 on the composite, it does not try to render an enormous file, but instead only renders the lower-left corner of the image cropped at 4K. To change this behavior, set a higher or lower pixel resolution. These assignments have no effect on files written to disk.

Creating Custom Listings for the Format Pop-Up

In the startup directory:

 
DefTimecodeMode(
  "Name", 
  fps, 
  numFramesToDrop,
  numSecondsDropIntervals, 
  numSecondsDropException
);


DefTimecodeMode("24 FPS", 24);
DefTimecodeMode("30 FPS DF", 30, 2, 60, 600);

These define the timecode modes for the Globals pop-up.

To set the default timecodeMode, use:

script.timecodeMode = "24 FPS"

Default Timecode Modes and Displays

In the startup or ui directory: 

script.framesPerSecond = 24;
script.timecodeMode = "24 FPS";
gui.timecodeDisplay = 0;

Set one or the other. Setting the timecodeMode allows you to use drop-frame settings. See above to set the Timecode Modes. The third line is to display the frames in the Curve Editor and Time Bar as frames or timecode. 1 = timecode, 0 = frames. The other timecode modes are: "25 FPS", "30 FPS DF" and "30 FPS ND".

Other Settings

Autosave Frequency

In the ui directory:

script.autoSaveDelay = 60;

This shows how often the autoSave script is done in seconds. The script is saved automatically in your User Directory as autoSave1.shk, autoSave2.shk, etc., up to autoSave5.shk. It then recycles back to 1. If you lose a script due to a crash, you can load in the autoSave script.

Undo Levels Amount

In the ui directory: 

gui.numUndoLevels= 100;

This shows how many steps of undo are available. Undo scripts are stored in the TEMP directory.

Amount of Processors to Assign to Interface

In the ui directory:

sys.maxThread = nrcGetAvailableProcessors();

This sets the number of processors when using the interface. The nrcGetAvailableProcessors automatically calculates and assigns all of them. If you only want to use a limited number of processors, assign that number here.

You can assign the number of processors to be used when batch processing with the -cpus flag. The default is 1. For example:

shake -exec my_script.shk -cpus 2

Font Size for Menus and Pop-Up Menus

In the startup directory: 


// It can take the following values: 
//tiny, small, medium, big, std
gui.menu.fontSize= "std";

This should be in a ui .h file, but it must be set before the interface is built, so it goes in a startup file. The example is "tiny". "std" is the default.

Open File Handling for FileIn Nodes

In the startup directory:

sys.closeIdleFiles = 0;

With this plug set to 0 (the default), Shake leaves all files referenced by FileIn nodes open even after the current frame has been rendered, when you work in the Shake UI. This is efficient as it eliminates the need for Shake to constantly reopen files while you make frequent adjustments that require re-rendering. However, if the number of FileIn nodes in a script exceeds the maximum number of open files allowed by the system, you may have problems.

Setting the sys.closeIdleFiles plug to 1 closes all files referenced by the FileIn nodes of your script after rendering is complete.

Note: The sys.closeIdleFiles plug only applies to FileIn nodes used to reference Tiff, Targa, DPX, and Cineon files.

Adding Functions to the Right-Click Menu

 In the ui directory:

 

nuiPushMenu("NRiNodeViewPopup",1);
  nuiPushMenu(
    "This makes a Sub-Menu",0
    );
    nuiMenuItem(
      "Grad", 
      nuiToolBoxMenuCall({{Grad()}})
);
nuiPopMenu();

This is an example that creates a subtab called “This Creates a Sub-Menu” in the Node View, and attaches the Grad function to its list. This is just one example. Take a look at the nrui.h file, where all right-click menus are built. The first line declares under what menu it is built, so typically these commands are added directly into the nrui.h file.

Adding Functions Into a Menu

 In the ui directory: 


nuiOpenMenu("Render");
nuiMenuSeparator();
nuiMenuItem(
  "Highend2D", 
  LaunchBrowser(
     "http://www.highend2d.com",1
  )
);
nuiPopMenu();

This creates an entry in the Render menu, split from the other entries by a separator.

Opening Scripts with Missing Macros

If you open a Shake script that contains a macro(s) that you do not have on your system, you have the option to load the script using a substitute node, or to not load the script at all using the macroCheck parameter in the Globals tab. To set the default macroCheck behavior to substitute a MissingMacro node, include the following in a .h file:

sys.useAltOnMissingFunc = 2

For information on the macroCheck parameter, see “The Global Parameters” table on page 96 of the Shake 3 Reference Guide.

Linking an HTML Help Page to a Custom Node

To link a node's HTML Help button to your own custom page, enter the following line into its ui.h file:

nuiRegisterNodeHelpURL ("MyCustomFunction", "http://www.apple.com/shake/");

Memory and the Cache

Shake incorporates two separate caches: a processing cache and an image cache.

The processing cache is mainly used to store image tiles generated by nodes that need surrounding pixels to perform their image processing operations during a render. Example nodes include the Warp, PinCushion, and Twirl nodes. The processing cache also provides secondary functionality for caching rendering buffers (in particular for the QuickPaint node that utilizes a full-frame rendering buffer), color look-up tables, and transformation matrices. The global plugs used to control the processing cache are as follows:

The image cache is used to store output images that nodes produce. By storing the entire output image, the image cache can effectively “bake” portions of the processing tree, thereby saving re-computation time. Whether or not a node’s image data is sent to the image cache primarily depends on the node’s position in the node tree. When editing, the nodes directly above the node that is currently being viewed have the highest priority. During playback, the node currently being viewed has the highest priority. The global plugs used to control the image cache are as follows:

Limits to Shake RAM Usage

Shake is currently compiled as a 32-bit application, which can theoretically address up to 4GB of virtual RAM (2^32). However, due to constraints imposed by the operating system and competition for RAM from other running applications (as well as the OS), most 32-bit applications have a practical limit of ~2GB of addressable RAM per process. This means that, even if you have a workstation that is loaded up with 4GB of RAM, each Shake process can only take advantage of about 2GB of that RAM. The good news is that, if you launch a FlipBook while running Shake on a system with 4GB ram, the FlipBook (as a separate process) will be able to take advantage of the additional 2GB of RAM and will be less likely to cache to disk.

So does this picture change with Panther (a 64-bit operating system) and G5 workstations configured with 8GB of memory? The short answer is “partly.” A 32-bit application running natively on a 64-bit OS will still be limited to ~2GB of addressable RAM. However, a G5 configured with 8GB of RAM running Panther can keep a larger number of applications in physical ram without having to swap out the application’s memory to disk. And Shake will be able to allocate larger contiguous segments of physical RAM, which means that large Shake scripts can be edited and rendered in less time.

The Processing Cache

The processing cache has a fast RAM-based component and a slower disk-based component. If the memory limit of the RAM-based component is exceeded, Shake will “roll off” image tiles to disk using an algorithm that is based partly on when the image was last used. A point of interest is that there is no memory limit imposed on the on-disk component of the processing cache.

The size of the RAM-based component of the processing cache is set in the nreal.h file using the cache.cacheMemory global plug. The default size is 96MB and Shake internally sets a 256MB upper limit on the size of this cache. This “internal” upper limit can be modified using the cache.cacheMemoryLimit plug to values greater than 256MB. However, this is only recommended when working on systems with > 2GB of RAM. The following general guidelines apply when setting the cache.cacheMemory plug:

A final point regarding the processing cache is that both the RAM-based component and the disk-based component are active in all of Shake’s run modes: GUI sessions, background renders, and renders launched from the command line.

The Image Cache

The primary objective of the image cache is to enhance interactivity when editing a Shake script. It does this by caching output image data from nodes in the compositing tree at, and near, the portion of the compositing tree being edited or viewed.

Similar to the processing cache, it has both a fast RAM-based component and a slower disk-based component. However, the disk-based component of the image cache is only active during GUI sessions (unlike the processing cache, which is active in all Shake run modes). In addition, the disk-based component of the image cache is limited in size and, when the disk cache fills up, Shake will discard image data using an algorithm similar to that used by the processing cache.

Not all of Shake’s processing nodes incorporate functionality for caching their output image data. For example, image generator nodes such as ColorWheel and the FileIn node do not incorporate image-caching functionality. This is because these nodes can regenerate an image in a computationally efficient manner, so there is little to be gained by caching their image data. Also, some of the color operators not incorporate image-caching functionality because they are computationally efficient. Finally, Shake will not cache the image data for nodes where the ratio of the area of the DOD to the area of the ROI is greater than 4, as a large portion of the image data is not needed for the final rendered image.

For the majority of nodes that do cache their image data, Shake assigns the image data one of the following three priorities:

Note: The Shake disk cache is persistent. If you quit Shake, and then open your script the next day, it calls up the same files that were cached the previous day.

Customizing Shake's Image Caching Behavior

This section provides details on how to customize Shake’s image caching behavior. For the controls that are global plugs, it's best to manually declare them by creating a .h file in the startup directory.

cacheMode

This control is located in the GUI under Globals > guiSettings.

The following guidelines apply when setting the cacheMode:

diskCache.cacheMemory

This global plug controls the size of the RAM-based component of the image cache. Larger values enable Shake to: (1) cache more of the node tree currently being edited/viewed -- which enhances interactivity, especially when recursively viewing nodes both near the top and near the bottom of the node tree, or (2) cache a larger number of images during playback -- which can greatly increase playback speed.

The default value for diskCache.cacheMemory is 64MB, which enables Shake to cache ~43 images (8bit @ 720x486) in the RAM-based portion of the image cache. The following guidelines apply when setting the diskCache.cacheMemory size:

diskCache.cacheMemoryLimit

Internally, Shake sets an upper limit of 512MB on the size of the RAM-based component of the image cache. This global plug allows users to override this limit. However, we only recommended overriding (increasing) this value when working with scripts with large image resolutions (>2K) and higher bit depths (float) on workstations with >2GB or RAM. Increase at your own risk.

diskCache.cacheSize

This global plug controls the size of the on-disk component of the image cache. Larger values enable Shake to keep more “high priority” images around that have been pushed out of the RAM-based component of the image cache. Remember that this component of the image cache is inactive during background or command line renders.

diskCache.cacheMaxFile

This global plug sets the maximum number of files that will be created in the on-disk component of the image cache. Larger values allow Shake to store a larger number of images, since each cached image is stored in a separate file. However, some file systems have limits on both the maximum number of open files allowed and the maximum size of those files, so you can use this parameter to reduce the number of files being used in the image cache if a file system limit is being exceeded.

diskCache.cacheMaxFileSize

The global plug sets the maximum file size (in bytes) that can be stored in the on-disk component of the image cache. Larger values allow Shake to store larger images, since each cached image is stored in a separate file. However, some file systems have limits on both the maximum number of open files allowed and the maximum size of those files, so you can use this parameter to reduce the size of the files being used in the image cache if a file system limit is being exceeded.

diskCache.cacheLocation

The directory to which disk cache files are written. By default, the cache is written to:

/var/tmp/Shake/cache

Note: Shake automatically creates the cache directories if they do not exist.

To free up disk space, you can remove this directory, but all caching information will be lost. This is not vital, however, to the script. It simply forces Shake to completely rerender the compositing tree.

diskCache.cacheDebug

This global plug is used to enable a mode in the GUI that indicates which nodes have cached their image data to disk. By default, this plug is set to 0. To enable image-caching diagnostics, set this plug equal to 1.

When image caching diagnostics are activated, Shake will print one of the following four messages in the GUI next to nodes that incorporate image caching functionality:

Note: During an editing session, the caching priority of a node can be changed (upgraded) if its data is accessed from the image cache multiple times.

The Curve Editor and Time Bar

Setting the Time Bar Frame Range

In startup directory: 

gui.timeRangeMin=1;
gui.timeRangeMax=100;

That pretty much says it all, doesn't it?

Default Timecode Modes and Displays

In the startup or ui directory: 

script.framesPerSecond = 24;
script.timecodeMode = "24 FPS";
gui.timecodeDisplay = 0;

Set one or the other. Setting the timecodeMode allows you to use drop-frame settings. See above to set the Timecode Modes. The third line is to display the frames in the Curve Editor and Time Bar as frames or timecode. 1 = timecode; 0 = frames.

File Path and Browsers Controls

Setting Default Browser Directories

In the ui directory: 

gui.fileBrowser.lastImageDir= "C:/pix/" ;
gui.fileBrowser.lastScriptDir= "$MYPROJ/shakeScripts/" ;
gui.fileBrowser.lastExprDir= "//Server/shakeExpressions/" ;
gui.fileBrowser.lastTrackerDir= "$MYPROJ/tracks/" ;
gui.fileBrowser.lastAnyDir= "C:/Jojo/" ;

You can assign specific directories for the Browser to look in when you start the interface. You can assign different directories to different types of files, such as scripts, images, trackers, and expressions.

Important: There must be a slash at the end of the path.

Using the UNC Filename Convention

In the startup directory: 

script.uncFileNames = 1;

Shake automatically assigns the UNC filename, that is, the entire file path name using the network address starting with //MachineName//DriveName/path. This ensures proper network rendering. However, you can turn this off by assigning the uncFileNames to 0, at which point local file paths are maintained. You can use local paths in either case, but they get converted when UNC is on.

Adding Personal Favorites Into the Browser

In the ui directory: 

nuiFileBrowserAddFavorite(
  "D:/icons/scr/"
); 
nuiFileBrowserAddFavorite(
  "$nr_train/"
);

All directories assigned here appear in your Favorites area of the Directories pop-up menu in the Browser for quick access. To also Bookmark a directory in the Browser, click Bookmark and then choose File > Save Interface Settings in the File menu. This saves a setting in your $HOME/nreal/settings directory.

Assigning a Browser Pop-Up to a Parameter

In the ui directory: 

nuxDefBrowseCtrl(
  "Macro.imageName",
	kImageIn
);
nuxDefBrowseCtrl(
  "Macro.imageName",
	kImageOut
);
nuxDefBrowseCtrl(
  "Macro.fileName",
	kAnyIn
);
nuxDefBrowseCtrl(
  "Macro.lookupFile",
	kExprIn
);
nuxDefBrowseCtrl(
  "Macro.scriptName",
	kScriptIn
);
nuxDefBrowseCtrl(
  "Macro.renderPath",
  kAnyOut
);

This assigns a folder button to a string so that you can relaunch the File Browser. The Browser remembers the last directories you used for any different type, so you can assign the type of file the Browser should look for as well with kImageIn/Out, etc. For example, if you have a macro that browses an image to be read in, use kImageIn, so when you click that button, it jumps to the last directory from which you read in an image.
Automatic Launching of the Browser When Creating a Node

In the ui directory: 

nuiToolBoxItem("ProxyFileIn",   
  {{ 
  const char *filename = getFileInName();
  filename ? ProxyFileIn(filename,0,2) :
  (image) 0 
  }} 
);

In this example, the Browser is called for the parameter filename in the ProxyFileIn macro. The macro has three parameters: Filename and two numbers (0 and 2). The getFileInName function automatically launches the Browser when the user creates this node in the interface. You can use:

Automatic Browser File Filters

In the ui directory: 

gui.fileBrowser.lastImageRegexp= "*.tif" ;
gui.fileBrowser.lastScriptRegexp= "*.shk" ;
gui.fileBrowser.lastExprRegexp= "*.txt" ;
gui.fileBrowser.lastTrackerRegexp= "*.txt";
gui.fileBrowser.lastAnyRegexp= "*";

You can assign specific filters for the Browser for different types of Browser activity. For example, if you only use Cineon files, you may want to use an assignment such as:

gui.fileBrowser.lastImageRegexp= "*.cin" ;

Function Tabs

Setting Number of Node Columns in a Tab

In the <ShakeDir>/include/nrui.h or a startup file: 

gui.doBoxColumns = 8;

This sets the number of columns for the nodes in the Tool Tab, which is sometimes called the “Do Box.” Unlike the other ui. h files, this must go in <ShakeDir>/include/nrui.h, placed right before the call to start building the Image tab. To activate it, uncomment the bold line in the nrui.h file: 

//These control the color of text on an inactive tab

gui.tabber.tint.red = .65;
gui.tabber.tint.green = .65;
gui.tabber.tint.blue = .63;


//gui.doBoxAltFxIcons = 1;
//gui.doBoxColumns = 5;

nuiPushMenu("Tools");
nuiPushToolBox("Image");
    nuiToolBoxItem("Average",   "const char *fileName = blah
    nuiToolBoxItem("Checker",	 Checker());
    nuiToolBoxItem("Color",	     Color());
    nuiToolBoxItem("ColorWheel", ColorWheel());
Using the Alternative Icons

In startup or the <ShakeDir>/include/nrui.h file: 

gui.doBoxAltFxIcons = 1;
gui.doBoxColumns = 8;

This calls the alternative icon set, which concentrates more on the name of the function. The alternative icons are stored in icons/fxAlt with the same name as the normal icons set, for example, Image.Average.nri, etc. The dimensions for these icons are 130 x 26. Because they are wider, you typically limit the columns to 5 in a normal Shake environment. For a macro on generating these icons, see the “Cookbook” section of the Shake 3 Tutorials. You can activate the icons in two places, either a startup file, or by uncommenting the following two bold lines in the nrui.h file:

//These control the color of text on an inactive tab

gui.tabber.tint.red = .65;
gui.tabber.tint.green = .65;
gui.tabber.tint.blue = .63;


//gui.doBoxAltFxIcons = 1;
//gui.doBoxColumns = 5;

nuiPushMenu("Tools");
nuiPushToolBox("Image");
    nuiToolBoxItem("Average", " const char *fileName = blah blah blah
    nuiToolBoxItem("Checker", Checker());
...
Attaching a Function to a Button in the Tabs

In the ui directory:

 

nuiPushToolBox("Image");
nuiToolBoxItem("Flock", Flock(0,0,0));
nuiPopToolBox();

This places an icon that you have created into a tab that you assign. In this example, the icon is placed in the Image tab. If you use a custom name, such as My_Macros, it creates that tab. The second line first attaches the icon, and then assigns the function with its default arguments to that button. They do not have to be the same name, but both are case sensitive. The icon is either found in <ShakeDirectory>/icons, your <UserDirectory>/icons, or in any directory pointed to with $NR_ICON_PATH. The icons have the following characteristics:

The section that says Flock(0,0,0) is the function of what that button actually does. You can assign any function to these—read in scripts, call multiple nodes, etc. If the function does not have default values for its parameters, they must be provided here.

Attaching a Function to a Button Without an Icon

In the ui directory: 


nuiPushToolBox("Image");
nuiToolBoxItem("@Flock", Flock(0,0,0));
nuiPopToolBox();

Note the @ sign before the icon name. This creates a button with whatever text you supply.

Creating Multiple Nodes With One Function

In the ui directory: 

nuiToolBoxItem(
  "QuickShape",    
  Blur(QuickShape())
);

You can create multiple nodes with one button click when you call up a function. For example, if you always attach a Blur node to a QuickShape, you can do this by embedding one function within another. The first argument for a function is usually the image input. By substituting the value (usually 0) with a different function, that function feeds into your first function. In the above example, QuickShape is fed into Blur.

Light Hardware Mode

In the ui directory: 

sys.hardwareType = 1;

This command opens Shake without any borders on buttons, making the interactivity a little faster for graphically slower machines. A value of 0 is the normal mode; a value of 1 is the lightweight mode. Note the artwork isn’t updated for the darker interface, so it looks a bit odd.

 Node View

Setting Default Node View Zoom Level

In the ui directory: 

gui.nodeView.defaultZoom=1;

These are plugs specifically for the Time View. They use the same hex syntax as the other color plugs.

Parameters Tab

These are commands you typically assign to help lay out your macros by setting slider ranges, assigning buttons, etc. These behaviors are typically assigned to specific parameters. They can be applied either globally (all occurences of those parameters) or to a specific function. For example, if there is a triplet of parameters named red, green, blue, Shake automatically assigns a color picker to it. However, for a parameter like depth, you'd want to specify actions based on if it's a bit depth related function (and therefore assign a button choice of 8, 16, or float bit depth) or a Z-depth related function, in which case you'd probably want some sort of slider. To assign it to a specific function, preface the parameter name with the function name, i.e, MyFunction.depth.

All parameters, unless overridden by Shake's factory-installed rules, are assigned a slider with a range of 0 to 1.

Assigning a Color Picker

In the ui directory: 

nuiPushControlGroup("Color");
    nuiGroupControl("Func.red");
    nuiGroupControl("Func.green");
    nuiGroupControl("Func.blue");
nuiPopControlGroup();
nuiPushControlWidget(
    "Color",
    nuiConnectColorTriplet(
      kRGBToggle,
      kCurrentColor,
      1
    )
);

This assigns a button to three sliders so that you can scrub across an image and retrieve color information. You can select the current color, the average color, the minimum color, or the maximum color values. You can also assign a toggle switch to select the input node’s color or the current node’s color. For example, for pulling keys, you probably want to use the input node color since you are scrubbing (usually) blue pixels, rather than the keyed pixels. You can also choose to return different color spaces other than RGB. Assigning a Color Picker creates a subtree of those parameters.

Notice that you must first group the parameters into a subtree (the first five lines of the above example).

Color Pickers automatically appear if you name your triplet red, green, blue or red1, green1, blue1 or red2, green2, blue2.

There are three parameters for the nuiConnectColorPCtrl function. The first one is the color space, which can be declared with either a string (for clarity) or an integer:

kRGBToggle  0
kHSVToggle  1
kHLSToggle  2 
kCMYToggle  3

The second parameter describes the type of value to be scrubbed—the current, average, minimum or maximum. Again, you can use either the word or the integer.

kCurrentColor  0 
kAverageColor  1
kMinColor   2 
kMaxColor  3

The last parameter is a toggle to declare whether you use the current node’s pixel values or the input node’s pixel values. You use either 0 or 1:

0 = current node
1 = input node

Use of the current node may possibly cause a feedback loop. Typically, for color corrections you use current node, for keyers, the input node.

Therefore, the above example creates a subtree called Color for the function called MyFunction. The scrubber returns RGB values, of which only the current value is returned. When the Color Picker is called, the Use Source Buffer is turned on.

Assigning the Old Color Picker

In the ui directory: 

nuiPushControlGroup("Func.Color");
    nuiGroupControl("Func.red");
    nuiGroupControl("Func.green");
    nuiGroupControl("Func.blue");
nuiPopControlGroup();
nuiPushControlWidget(
    "MyFunction.Color",
    nuiConnectColorPCtrl(
      kRGBToggle,
      kCurrentColor,
      1
    )
);

This is an older version of the Color Picker without the cool extra controls.

Changing Default Values

In the <ShakeDir>/include/nrui.h file: 

nuiPushToolBox("Color");
    nuiToolBoxItem("Add",	    Add(0,0,0,0,0,0));
    nuiToolBoxItem("AdjustHSV",	    AdjustHSV(0));
    nuiToolBoxItem("Brightness",    Brightness(0,1));
    nuiToolBoxItem("Clamp",	    Clamp(0));
    nuiToolBoxItem("ColorCorrect", ColorCorrect(0));

...

In the include/nreal.h file, most functions have their default values declared, but not all of them. To override the default values when you call the function, modify the line that loads the function in the interface. If every parameter in a function has a default value in a function, you can call the function with something like:

nuiToolBoxItem("Clamp", Clamp(0));

Normally, Clamp has about 8 values. Here, the 0 represents in the first argument, the input image. 0 is used to indicate that no images are expected to be inserted, so you can attach it to the active node. However, you can add additional parameters. For example, the Brightness line above it has (0,1), 0 for the image input (no input) and 1 for the brightness value. Change the 1 to a different value to override it. You only need to supply the parameters up to the one you want. For example, the following is the call for the Text function:

nuiToolBoxItem("Text", Text());

To override the default font for the Text function, you have to supply the width, height, bytes, text, and finally the font. The rest you can ignore afterward:

nuiToolBoxItem("Text",	    Text(
  GetDefaultWidth(), 
  GetDefaultHeight(),
  GetDefaultBytes(),
  "Yadda Yadda",
  "Courier"
  )
);

Grouping Parameters Into a Subtree

 In the ui directory: 

nuiPushControlGroup("Func.timeRange");
    nuiGroupControl("Func.inPoint");
    nuiGroupControl("Func.outPoint");
    nuiGroupControl("Func.timeShift");
    nuiGroupControl("Func.inMode");
    nuiGroupControl("Func.outMode");
nuiPopControlGroup();

This groups parameters into a subtree that can be opened and closed by the user. This example, although it says "Func", is for the FileIn node.

Setting Slider Ranges

 In the ui directory: 

nuiDefSlider(
  "Funct.yPan", 0, height
);
nuiDefSlider(
  "Funct.angle", -360, 360
);
nuiDefSlider(
  "Funct.aspect", 0, 2, .2, .01
);

Even though the sliders are in relatively the same position, there are different numbers in the text fields. You can set slider ranges and precision with this function. The first line assigns a slider range just for the yPan parameter of the Move2D function. Note the use of the height variable so the range adjusts according to the input image. The second line assigns a range for the angle parameter in any node. The third line also has optional precision parameters, which are granularity and notch spacing.

Pop-Up Menus

 In the ui directory: 


nuxDefMultiChoice("Defocus.shape", 
"fast gaussian|fast box|circle"
);


This pop-up menu, from the Defocus function, allows you to use a pop-up menu for strings. Note this only supplies strings and not numbers, so you have to do some tricky math inside the macro itself. For more information, see "Script Manual" on page 692 of the Shake 3 Reference Guide.

Creating Radio Buttons

 In the ui directory: 

nuxDefRadioBtnCtrl(
   "Text.xAlign",
   1, 1, 0, 
   "1|ux/radio/radio_left", 
   "2|ux/radio/radio_center", 
   "3|ux/radio/radio_right"
);

This example is for the Text node. This code creates a series of radio buttons that are mutually exclusive. The naming convention assumes that you have four icons for each name, with the icon names name.on.nri, name.on.focus.nri, name.off.nri, and name.off.focus.nri. If no icons exist, you can choose to not use icons, which then gives a label with an on/off radio button instead. The code has these parameters:

nuxDefRadioBtnCtrl(
   const char *name, 
   int useIcon, 
   int useLabel, 
   int animatable,            
   curve string state0, ....
);

You can place as many icons as you want. The height of Shake’s standard parameters icons is 19 pixels, though this can change. The output parameter for Primatte and Keylight is a good example.

You can make your own radio buttons with the RadioButton function. This function is discussed in the “Cookbook” section of the Shake 3 Tutorials (or under doc/cook/macros).

Creating Push-Button Toggles

 In the ui directory: 

nuxDefExprToggle("Func.parameter", 
  "repl.nri|repl.focus.nri", 
  "interp.nri|interp.focus.nri",
  "blur.nri|blur.focus.nri"
);


This assigns a series of buttons to toggle through integers starting at 0. The first line is assigned a value of 0, the second line assigned a value of 1, the third assigned a value of 2, etc. You can place as many toggles as you want. There are two buttons for each assignment, the normal button, and a second button for when the cursor passes over the button to signify that you can press it. Note the standard buttons are all in the subdirectory ux, but this is not a requirement. Shake includes a series of precreated icons that are packed into the icons.pak file and are inaccessible to the user, but are understood by this code. Your custom icons can be any size, but the default height is 19 pixels. You cannot have an alpha channel attached to an icon. Use SetAlpha (set to 0) or Reorder (set to rgbn) to remove the alpha channel. They can be placed in <ShakeDirectory>/icons, the <UserDirectory>/icons, or $NR_ICON_PATH.

Creating On/Off Buttons

 In the ui directory: 

nuxDefExprToggle("Func.param");

This is similar to the push-button toggles, but you only have two values, on and off—off a value of 0, and on a value of 1. The icon assignment is automatic.

Making a Parameter Non-Animatable

 In the ui directory: 

nriDefNoKeyPCtrl("DilateErode.soften");

This designates that no autokey buttons appear.

Placing a Curve Editor Into a Parameter Tab

 In the ui directory: 


nuiPushControlGroup("colorExpr");
  nuiGroupControl("Lookup.rExpr"); 
  nuiGroupControl("Lookup.gExpr"); 
  nuiGroupControl("Lookup.bExpr"); 
  nuiGroupControl("Lookup.aExpr"); 
nuiPopControlGroup();

//Makes all curves invisible by default
registerCurveFunc("colorExpr"); 
//This makes all curves visible by default
registerCurveFuncVisible("colorExpr"); 

gui.colorCtrl.curveEditorDirection = 0; 
//When it is 1, the layout it vertical
//When this equals 0, the layout is 
//horizontal

This code loads a Curve Editor embedded inside the Parameter tab. The first six lines of code simply group parameters together. The last line then attaches the parameters to the Curve Editor embedded in the Parameter tab.

Linking an HTML Help Page to a Custom Node

To link a node's HTML Help button to your own custom help page, enter the following line into its ui.h file:

nuiRegisterNodeHelpURL("MyCustomFunction", "http://www.apple.com/shake/");

Viewers

This section discusses Viewer settings and onscreen controls.

Settings

Setting Maximum Viewer Resolution in the Interface

In the ui directory:

gui.viewer.maxWidth = 4096;
gui.viewer.maxHeight = 4096;

By default, Shake protects the user from test rendering an enormous image by limiting the resolution of the Viewer to 4K. If the user accidentally puts a Zoom set to 200 on the composite, it does not try to render an enormous file, but instead only renders the lower-left corner of the image cropped at 4K. To change this behavior, set a higher or lower pixel resolution. These assignments have no effect on files written to disk.

Onscreen Controls

Onscreen controls are automatically built according to how you name your parameters in your macro, with one exception—to make a cross-hair control. The following is the list of parameters it takes to make certain controls. For the illustrations, the controls are attached to their appropriate functions. For example, the pan controls are attached to a Pan function and scaling to a Scale function. Simply naming the parameters does not necessarily give you the functionality you want.

Panning Controls

 In the startup macro file: 

float xPan=0,
float yPan=0


This gives you the lattice to pan around. You can grab anywhere on the cross bars.

Scaling Controls

 In the startup macro file:

 
float xScale=1,
float yScale=1,
float xCenter=width/2,
float yCenter=height/2


This gives you the border and center controls to change the scale center. You can grab on a corner to scale X and Y or on an edge to scale X or Y.

CornerPin Controls

 In the startup macro file: 

float x0=0,
float y0=0,
float x1=width,
float y1=0,
float x2=width,
float y2=height,
float x3=0,
float y3=height
In the UI File:
nuiPushControlGroup(
  "Func.Corner Controls"
);
	nuiGroupControl("Func.x0");
	nuiGroupControl("Func.y0");
	nuiGroupControl("Func.x1");
	nuiGroupControl("Func.y1");
	nuiGroupControl("Func.x2");
	nuiGroupControl("Func.y2");
	nuiGroupControl("Func.x3");
	nuiGroupControl("Func.y3");
nuiPopControlGroup();


Grab any corner or the cross hair in the middle to adjust the position of your image. The grouping code for the UI file is included, so you do not have to look at all eight parameters in your list.

Box Controls

 In the startup macro file:

 
int left = width/3,
int right = width*.66,
int bottom = height/3,
int top = height*.66
In the UI File:
nuiPushControlGroup(
  "MyFunction.Box Controls"
);
	nuiGroupControl("MyFunction.left");
	nuiGroupControl("MyFunction.right");
	nuiGroupControl("MyFunction.bottom");
	nuiGroupControl("MyFunction.top");
nuiPopControlGroup();


This creates a movable box. You can grab corners or edges, or the inside cross hair. This example is applied to a SetDOD function. Layer–Constraint and Transform–Crop also use these controls. In this example, integers are used for values that assume you are cutting off pixels, but you can also use float values.

Offset Controls

 In the startup macro file:

  
float xOffset=0,
float yOffset=0


This is similar to the Pan controls, except you get a cross hair. This is used by the Other–DropShadow function.

Rotate Controls

 In the startup macro file:

  
float angle = 0,
float xCenter=width/2,
float yCenter =height/2,


This gives you a rotation dial and a center control. This example is plugged into a Rotate function.

Point Controls

 In the startup macro file: 


float xCenter = width*.33,
float yCenter = height*.33,
float xPos = width*.66,
float yPos = height*.33,
float myPointX = width/2,
float myPointY = height*.66


UI file:

nuiAddPointOsc("Func.myPoint");


These three sets of parameters create a cross hair control. Center and Pos are default names—the Center pair is also associated with the angle and the scale parameters. However, the last point is completely arbitrary, as long as it ends in an uppercase X and Y. In the ui file, you must also declare that these are an XY pair.

Radius Controls

 In the startup macro file:

 

 
float radius = width/6,
float falloffRadius = width/6,
float xCenter=width/2,
float yCenter = height/2


This is basically for RGrad, but maybe you can do more with it...

Template Preference Files

You can add additional parameters and default settings by adding files into the startup/ui/templates directory. Each time Shake is launched, it adds these extra parameters. For example, if you always want the Proxy Filter to be “box” instead of “default,” and you always want a slider in the Globals tab called switch1, create a .h file under the templates directory with:

SetProxyFilter("box");
curve int switch1=0;

Basically, take a saved script and strip out the lines you want to set as defaults, and save it as a .h file into templates.

Changing the Default QuickTime Configuration

You can change the default QuickTime configuration that appears when you set the fileFormat parameter of a FileOut node to QuickTime. The default QuickTime configuration is also the configuration that Shake falls back on when a script is opened with a FileOut note that's set to use a QuickTime codec that's not available on that computer.

The default settings in Shake are limited to the ones you find in the standard QuickTime compression settings dialog.

To change the default QuickTime configuration:

  1. Create a script with a FileOut node.
  2. Select the FileOut node, and choose QuickTime from the fileFormat pop-up menu in the Parameters tab.
  3. Click codecOptions, then set the codec options in the Compression Settings dialog.
  4. Save the script.
  5. Open the script in a text editor and find the definition of the FileOut node you created. After the name of the codec, you'll see a 0, then a long, seemingly nonsensical string of text in quotes. Copy the long nonsensical string, but not the quotes.
  6. Create a .h file in your include/startup directory. Type: 
sys.QTDefaultSettings = “x”;

where x is the long string you copied, in quotes with a semi-colon at the very end of the line. Here is an example:

sys.QTDefaultSettings = "100W@u3000WDcsuHA#M000E@4J3In8q5CBRZ0VY2LKKPgATB3A9KSC7
gXaC30q8vW16OG5Koq10h2A5HIvi00ieKA9WT6a1rS9hH8dqIEiBqOHT0SJEZ8HHc8qtf4rlxSAP9WY
wcYJHfMMCKpWXYn2W893LCsk080000@00000000000;";

The above declaration sets the Uncompressed 10-bit 4:2:2 codec as the default.

The default settings in Shake are limited to the ones you find in the standard QuickTime compression settings dialog.

Note: If the default codec you've specified is not available, a message is sent to the console, and the default codec reverts to Animation.

Environment Variables for Shake

This section discusses two ways to set environment variables, and the variables recognized by Shake. At the end of the section, some examples of aliases are provided.

Warning Incorrectly setting environment variables can lead to problems running Shake and with your operating system. If you are not comfortable with changing these types of settings, consult your system administrator for guidance.

Environment variables are strings of information, such as a specific hard drive, file name, or file path, set through a shell (for example, in Terminal on an OS X system) that is associated with a symbolic name (that you determine). This information is stored in a hidden file. Each time you launch Shake, the operating system and the Shake application look at the hidden file to set the environment variables. In other words, defining environment variables is the equivalent of setting user-defined system preferences.

As a simple example, you can set an environment variable that specifies a folder that Shake scans (on launch) for additional fonts used by the Text or AddText nodes.

To set environment variables on a Macintosh OS X system, create and edit a “.plist,” or property list, file. Using the .plist sets variables for Shake whether it is launched from the Terminal or from the Shake icon.
Using the above example of a font folder, to instruct Shake to read the /System/Library/Fonts folder, set the following environment variable in your .plist file: 

<key>NR_FONT_PATH</key>
<string>/System/Library/Fonts</string>

Another way to define environment variables is to use the setenv command in a .tcshrc (enhanced C shell resource) file. Each time the Terminal is launched, the .tcshrc file is read. The environment variables defined by the .tcshrc file are only read by Shake when launched from the Terminal.

Using the above example of a font folder, to instruct Shake to read the /System/Library/Fonts folder, set the following environment variable in your .tcshrc file:

setenv NR_FONT_PATH /System/Library/Fonts

Note: The .tcshrc file can be used on all Shake platforms (OS X, Linux, and IRIX).

Common uses for a user’s personal .plist or .tcshrc file include:

Creating the .plist Environment File

Each time you log in, the system searches for an environment file, named environment.plist. This file sets an environment for all processes (launched by the logged-in user). In the Terminal, you create a directory called .MacOSX that contains the environment file. You also create the environment file (using a text editor), and move the file into the .MacOSX directory.

To set environment variables in Macintosh OS X using the .plist file:

1  Log in using your personal login.

2   Launch Terminal.

By default, you should be in your Home ($HOME) directory. Your Home directory is your own directory in the Users folder. For example, if John Smith logs in and launches the Terminal, the following message is displayed in the Terminal:

john-smiths-Computer:~] john%

3   In the Terminal, type the following command to create a directory in your Home directory called .MacOSX:

mkdir $HOME/.MacOSX

and press Return.

An invisible directory (indicated by the “ . ” in front of the directory name) is created in your Home directory.

To ensure the .MacOSX directory was created, type:

ls -als

and press Return.

All files, including the new invisible .MacOSX directory, are listed.

4   Next, launch TextEdit (or other text editor) to create a file to set your variables.

Note: If you have installed and are familiar with the Apple Developer tools, you can use the Property List Editor application to create or edit variables. The Property List Editor application is located in Developer/Applications.

5  In the text document, create the following file (if reading this in the PDF version of the reference guide, you can copy the following and paste it into the text document) and edit the information.

Note: The following is an example file for instructional purposes only.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
<key>MyProject</key>
<string>/Documents/MyBigFilm</string>
<key>NR_INCLUDE_PATH</key>
<string>/Documents/MyBigFilm/macros</string>
<key>NR_ICON_PATH</key>
<string>/Documents/MyBigFilm/icons</string>
</dict>
</plist>

This sets the variable MyProject to /Documents/MyBigFilm. This tells Shake that all files associated with MyProject (that could be a script, directory, etc.) are located in /Documents/MyBigFilm. As a result, if you type MyProject in the browser, it returns /Documents/MyBigFilm, and can then be set as a favorite. This file also sets the NR_INCLUDE_PATH (points to the directory or directories that you want Shake to scan for macros and personal machine or user interface settings), and NR_ICON_PATH (points to a directory that you can save your own icons for Shake functions).

6   In TextEdit, choose Format > Make Plain Text.

The document is converted to a .txt file.

7  Choose File > Save.

In the “Save as” field of the Untitled.txt window, enter:

environment.plist

Be sure to remove the .txt file extension.

8  Save the file to your Home directory (in TextEdit, select Home in the “Where” pop-up list), and click Save.

9  In the Save Plain Text window, click “Don’t append.”

The file is saved in your Home directory with the extension .plist.

10 Quit TextEdit.

In order for Shake and your system to access the environment variables, the environment.plist file must be saved to the .MacOSX directory (created in step 3).

11 To save the environment.plist file to your .MacOSX directory, move the file (using the Terminal) from your Home directory to the .MacOSX directory. In the Terminal, do the following:

12 Log out and then log in again.

To edit the .plist file:

  1. In the Finder, choose Go > Go to Folder (Command+Shift+G).
  2. In the “Go to the folder:” text field, enter the path to the invisible .MacOSX folder. For example: /Users/john/.MacOSX
  3. Click Go. The environment.plist file appears in the folder.
  4. Open the .plist file in TextEdit (or other text editor).
  5. Once your changes are made, choose File > Save.
  6. Quit TextEdit.

Using the .tcshrc Environment File

You can also set environment variables (or aliases) using a .tcshrc file. Like the above .plist file example, you can create the .tcshrc file in a text editor, or directly in a shell using vi, pico, or other shell editor. Unlike the .plist file, however, you do not save the .tcshrc file to the .MacOSX directory. Instead, the .tcshrc file is saved into your Home ($HOME) directory.

Usually, you define environment variables in tsch with the setenv command, for example:

setenv audio /Volumes/shared/footage/audio_files/

This variable instructs Shake to automatically look in /Volumes/shared/footage/audio_files/ when you import an audio file into Shake.

At login, the default /etc/csh.cshrc, followed by any .tcshrc files in your login directory, is run. This sequence is repeated whenever a new tsch is spawned, for example, when you launch Terminal.

Note: As mentioned above, Shake only reads the .tcshrc environment file when Shake is run from the Terminal (the file is not applied when Shake is launched from the application icon).

To add a variable for Terminal commands, enter the following formatting (edit to suit your own project) into $HOME/.cshrc or $HOME/.tcshrc:

setenv NR_INCLUDE_PATH " //Biggo/proj/include;/Documents/shake_settings/include"

The following is an example of .tcshrc file for illustration purposes only:

setenv shake_dir /Applications/Shake3/shake.app/
   Contents/MacOS/shake
setenv shk_demo /Documents/project_03
set path = (. $shake_dir $path)
setenv NR_INCLUDE_PATH /Documents/project_03
setenv NR_FONT_PATH /System/Library/Fonts
alias ese vi $HOME/.tcshrc
alias s. source $HOME/.tcshrc
alias lt ls -latr
alias ui cd $HOME/nreal/startup/ui
alias st cd $HOME/nreal/include/startup
alias shake $shake_dir

This file sets the Shake directory, as well as points to the directories that you want Shake to scan for macros, user interface settings, etc. (/Documents/project_03), and fonts (/System/Library/Fonts).

Note: Alias definitions or environment variables saved in a .tcshrc file, are read the next time you log in. To make the alias or environment variable effective immediately, update your alias definition by sourcing out .tcshrc. Type the following:

source .tcshrc

To edit the .tcshrc file, use pico or vi (or other shell editor). Once your changes are made, save the .tcshrc file. Like the .plist example above, you can edit the .tcshrc file in a text editor.

Shake Variables

Shake recognizes the following variables:

shell variables: The Shake Browser recognizes an environment variable, for example, $pix in the Browser if Shake is run with that environment setting.

NR_CINEON_TOPDOWN: When set, that is,

setenv NR_CINEON_TOPDOWN

Cineon frames are written in the slower top-down method for compatibility with other less protocol-observant software.

NR_FONT_PATH: Points to a directory where you want Shake to scan for additional fonts used by the Text/AddText functions. Fonts can also be found in the <UserDirectory>/fonts directory.

NR_ICON_PATH: Points to a directory where you can save your own icons for Shake functions. Icons can also be found in the <ShakeDirectory>/icons or the <UserDirectory>/icons directories.

NR_INCLUDE_PATH: Points to the directory or directories that you want Shake to scan for macros and personal machine or UI settings. These directories should have startup/ui as subdirectories. For example:

setenv NR_INCLUDE_PATH /shots/show1/shake_settings

should have /shots/show1/shake_settings/include/startup/ui

NR_SHAKE_LOCATION: Points Shake to a nonstandard installation area for IRIX. Default installation is /usr/nreal/<ShakeDir> (for IRIX).

NR_TIFF_TOPDOWN: This is identical for NR_CINEON_TOPDOWN, except it applies to TIFF files.

TMPDIR: Points to the directory you want to use as your temporary disk space directory.

NR_GLINFO: Information is printed for Flipbooks.

To Test Your Environment Variable

There is a simple way to test if your environment variable exists. In a Terminal, type echo, followed by the environment variable, for example:

echo $myproj

and the proper value should be returned.

Alias

An alias is a pseudonym or shorthand for a command or series of commands, for example, a convenient macro for frequently used command or a series of commands. You can define as many aliases as you want (or, as many as you can remember) in a .tcshrc file.

To see a current list of aliases, type the following in a shell:

alias

To start Shake from the Terminal window:

Alias shake /Applications/Shake3/shake.app/Contents/MacOS/shake

To determine how many users are currently working on the system:

Alias census 'who | wc -l'

To display the day of the week:

alias day date +"%A"

To display all Shake processes that are running:

alias howmany 'ps -aux | grep shake'


Interface Devices and Styles

This section discusses considerations when using a Stylus, setting mouse behavior, using a two-monitor system, and setting the monitor resolution on an IRIX system.

Using a Stylus

Left-Handed Users

If you are left-handed, set the mouse behavior within the operating system itself. On IRIX, the settings are located in the Desktop > Customize > Mouse page tab.

Dual-Head Monitors

Choose View > Spawn Viewer Desktop to create a new Viewer window that floats above the normal Shake interface. You can then move the Viewer to a second monitor, clearing up space on the first for node editing operations. This only works when both monitors are driven by the same graphics card.

The following is a handy ui Directory command to automatically create the second Viewer Desktop:

gui.dualHead= 1;
// This is an example of what you can do to open a second
// viewer desktop on the other monitor.
if(gui.dualHead) spawnViewerDesktop(1290,10,1260,960);

For information on using a broadcast video monitor, see “Using a Broadcast Monitor” on page 63 of the Shake 3 Reference Guide.

Setting the Monitor Resolution for an IRIX System

To set your resolution on an SGI system, use either xsetmon (a graphical interface), or use the command-line setmon (these are SGI specifications).

To set your resolution, use the command “setmon” in the command line, AS ROOT: 

/usr/gfx/setmon -x 1600x1024_72

The allowed values depend on your graphics card. If you are using an Octane with MXI graphics, go to the /usr/gfx/ucode/MGRAS/vof/2RSS/ directory to see the allowed choices. In the case of the MXI Octane, you have: 

1024x768_60.sdb 1280x1024_72.sdb 
1024x768_60p.sdb 1280x1024_76.sdb 
1024x768_72.sdb 1280x492_120s.sdb 
1024x768_76.sdb 1280x960_30i.sdb 
1024x768_96s.sdb 1600x1024_72.sdb 
1024x768_96s_vs.sdb 1600x1200_60.sdb 
1280x1024_49.sdb 1600x1200_60_32db.sdb 
1280x1024_50.sdb 1920x1035_60.sdb 
1280x1024_50_2f.sdb 1920x1080_60_32db_gdm24w.sdb 
1280x1024_59.sdb 616x492_140os.sdb 
1280x1024_60.sdb 640x480_60.sdb 
1280x1024_60_2f.sdb 640x486_30i.sdb 
1280x1024_60p.sdb 768x576_25i.sdb 
So: /usr/gfx/setmon -x [settingFileWithoutExtension]

In both cases, you must log out and log in again; no reboot is needed.

Customizing the FlipBook

The following arguments have been added to the flipbook executable as global plugs. This lets you specify an external flipbook to come up as the default. Specify these plugs using a .h file in the startup directory. The global plugs and their default values are:

gui.externalFlipbookPath = "shkv"; // the flipbooks name -- this should include the full path
gui.flipbookStdInArg = "-"; // instructs the flipbook to take data from StdIn
gui.flipbookExtraArgs = ""; // allows you to enter any extra arguments the flipbook needs.
gui.flipbookZoomArg = "-z"; // sets the zoom of the flipbook
gui.flipbookTimeArg = "-t"; // the time range argument
gui.flipbookFPSArg = "-fps"; // the frames per second argument

Note: If the specified external flipbook doesn't support one of these arguments, setting its value to an empty string ("") prevents that value from being passed to it.

Configuring Additional Support for Shake Qmaster

You can enable additional support for Shake Qmaster by adding the following global plug to a .h file in the startup directory:

sys.useRenderQueue = “Qmaster”;

This setting causes additional options to appear in the Render Parameters window when you choose Render > FileOut Nodes. These options become visible when you open the renderQueue disclosure control.

If Shake Qmaster isn’t installed but the sys.useRenderQueue plug is declared, a message is sent to the console upon startup, and the following options do not appear.

RenderQueue Options