Conditionals

Portions of the scene file can be excluded from consideration during parsing, depending on conditional statements that bracket the portions of the scene file to be excluded. The primary example for this is protecting included files from double inclusion. For example, a file x.mi included with $include might begin with the statements

    $ifndef "x_mi"
    set "x_mi" "true"

    # normal contents of x.mi

    $endif

The following conditional statements are supported:

    $ifdef "key"  
    $ifndef "key"  
    $ifeq "key" "constant"  
    $ifneq "key" "constant"  
         
    $else  
    $elseifdef "key"  
    $elseifeq "key" "constant"  
         
    $endif

The $ sign must be in the first column of the line. The usage always follows the pattern if...endif, or if...else...endif. Conditionals can be nested. As a convenience, an else can be concatenated with another if; in this case only one endif is needed because the concatenated forms do not require an endif of their own.

There are two forms of if statements: those that check whether a key is present, and those that compare two strings. The key strings take one of two forms:

A string without curly braces. This is interpreted as the name of a variable that can be set with the set command. If the variable was set, it is said to be defined, and its value is the value from the set command. If there was no such set command, or a set command without a value, it is said to be undefined.
A string containing curly braces. This string goes through registry substitution, which will replace registry keys like {var}, and environment references of the form ${var} (return value of var) or ${?var} (return "1" if defined otherwise empty string) with the appropriate values. If this results in a non-empty string, the key is said to be defined, and undefined otherwise.

The constant strings take only the second form; variable lookups are not possible here. A constant without curly braces will be treated as a literal string, not a variable name.

Note that conditionals can also be useful in rayrc startup files. For example, paths and all sorts of other platform-dependent setup keys can be made dependent on a single variable. For example:

    registry "{EXT}" value "so" end registry
    $ifeq "{EXT}" "so"
    echo "hello, penguin"
    $endif

The following example demonstrates the power of conditionals together with registry substitution to detect the runtime environment of mental ray:

    $ifdef "${?OS}"
    $ifeq "${OS}" "Windows_NT"
        registry "{PLATFORM}" value "windows" end registry
    $endif
    $elseifdef "${?OSTYPE}"
    $ifeq "${OSTYPE}" "darwin"
        registry "{PLATFORM}" value "macosx" end registry
    $elseifeq "${OSTYPE}" "linux"
        registry "{PLATFORM}" value "linux" end registry
    $endif
    $endif

    # If system could not be detected set a default.
    $ifndef "{PLATFORM}"
        registry "{PLATFORM}" value "unix" end registry
    $endif
    
    # Print registry substituted message at 'info' verbosity.
    registry "{whatifound}"
        echo "I think this is a {PLATFORM} system"
    end registry

    $lookup "{whatifound}"

Conditionals can be used even in the middle of a statement, as long as the conditional is on its own line. (mental ray ignores whitespace and line breaks in statements.) This introduces a conflict where a conditional follows a set statement with only a single argument, which normally clears the named variable, and that same variable is used in the conditional:

    set "var"
    $ifdef "var"

Is the variable being unset so the conditional should be false, or is the second argument of the set command inside the conditional? mental ray cannot know this. It assumes the latter, so the set statement is considered unfinished and has no effect on the conditional.

The conditional statements are:

    $ifdef "key"

Proceed if key is defined, or skip to the matching $else or $endif otherwise.

    $ifndef "key"

Proceed if key is not defined, or skip to the matching $else or $endif otherwise.

    $ifeq "key" "constant"

Proceed if key evaluates to the same string as value, or skip to the matching $else or $endif otherwise.

    $ifneq "key" "constant"

Proceed if key does not evaluate to the same string as value, or skip to the matching $else or $endif otherwise.

    $else

Reverse the condition tested in the previous $if x or $elseif x test, and proceed if we were skipping or skip if we were proceeding, until the next $endif. Only one $else is allowed per $if x, and it must be last in any $elseif x chain.

    $elseifdef "key"

A combination of $else and $ifdef. It does not need its own $endif. For example, $if x ... $elseifx ... $elseif x ... $else ... $endif is legal.

    $elseifeq "key" "constant"

Similarly, a combination of $else and $ifeq.

    $endif

Finishes a conditional sequence that has started with $if x.