CREATING YOUR OWN COMMAND TYPES

This section is an explains how to define group types in the file Janus_CommandTypes.cfg. Like Janus_GroupTypes.cfg, Janus_CommandTypes.cfg is structured like an INI file and they contain identical parameters, although command types have some syntactical differences.

Basics
First, be aware that commands are applied to groups, and that their priority is lower than of group. This was discussed earlier in the Group-Command Relationship section.

Second, command types distinguish between active and other groups, and layer types. This changes their syntax from group types. Here is an example:

[MyCommandType]
ACTIVE.FG.UBC=true
OTHER.BG.UBC=false
GLOBAL.BG.UBA=black

The first element (ACTIVE, OTHER, or GLOBAL) is called the group indicator. The second element (FG or BG) is the layer indicator. The third element is the directive which may be a group directive or a scene directive. An equals sign follows and then the value of the directive is inputted.

Whitespaces to left or right of the equals sign is not allowed.

Going back to the example command type above, we translate what it means:

ACTIVE.FG.UBC=true
(if the group being processed is the active group, and if the command is being run as a foreground layer, then turn the group's UnseenByCamera parameter 'on'.)

OTHER.BG.UBC=false
(if the group being processed is one of the other groups, and if the command is being run as a background layer, then turn the group's UnseenByCamera parameter 'off'.)

GLOBAL.BG.UBA=black
(whatever group is being processed – active or other -, and if the command is being run as a background layer, then switch the UnseenByAlpha parameter of that group to “Constant Black”.)

Command types can use scene directives in the form of the directive SCENE.CMD. An example will illustrate this. For example we have a command type such as:

[specialBTY]
inherit=BTY
SCENE.CMD=fogtype2
SCENE.CMD=fogColor255,255,255

Then we have a command that calls this type:

specialBTY.BG.bgColor0,0,0.box

What actually happens here is that Janus will append the values of the parameters of SCENE.CMD into the current pass:

specialBTY.BG.bgColor0,0,0.fogtype2.fogColor255,255,255.box

Furthermore SCENE.CMD can also accept group directives.

SCENE.CMD=UBABOTHON

However, since SCENE.CMD appends it to the subcommand for execution, its behavior changes so that you are not able to utilise layer indicators.

Syntax
All As explained in the overview, directives executed as a subcommand is different syntactically when it is used as a directive in a command type. The syntax for directives in command types is identical to group types, and as such you can look at them in the Syntax section of Creating Your Own Group Types. The only addition to command types, however, is the SCENE.CMD directive. A SCENE.CMD directive will append the directive's value into the subcommand before executing it. You may use SCENE.CMD directives as many times as you need.

SCENE.CMD=fogMinDist"535.25"
SCENE.CMD=outputsubdir"occ"
SCENE.CMD=RENDERLINESOFF

Command Inheritance
Inheritance is a principle that goes in the very heart of how Janus works. Type inheritance means that attributes that belong to one type can inherit, or be inherited by another type, giving you a cascading application of attributes. If you wanted to specify a command type which modifies radiosity parameters, for example, you can always inherit that command type whenever you need a special case to modify radiosity. Perhaps you have a test render preset that calls this radiosity-only command type.

In its very essence, the render pass (as viewed in text in the cmd line) is the most fundamental thing that Janus sees. When a command type is assigned to this render pass, it inherits the settings of the command type. This is the same as with Group Types. But the difference between Command Type inheritance versus Group Type inheritance is that groups can only inherit once, and inherit only one group type. Command types, however, can inherit multiple ones, and have various ways of doing so: the CTCMD subcommand will inherit another command type; a composite command type offers a different kind of inheritance by executing the command types one-by-one, as if in a queue; the actual command type is based on inheritance, too, and is defined through the use of the INHERIT keyword (described below).

By designing building blocks of smaller parameters, you can use these building blocks for larger command types. Take this example of a shadow-catcher command type.

[SHDC]
//catches shadows only
//active replaces with shadowCatcher.srf
INHERIT=BTYRAW
INHERIT=BTY2
ACTIVE.BOTH.SRF="shadowCatcher.srf"
SCENE.CMD=outputsubdir"shdc"
SCENE.CMD=fogtypeoff

The SHDC command type is already inheriting BTYRAW and BTY2 (which we won't get into at this point). But it also has its own parameters. If I apply this command type, all active groups will have their surfaces replaced with my shadowCatcher.srf. Now, let's say I didn't want any self-shadowing to occur. I just want it to receive shadows from others. But I also want to keep my options open, and create another command type instead of overwriting this. So this is how I will write this new command type.

[SHDC_EX]
//extrovert shadowcatcher
INHERIT=BTYRAW
INHERIT=BTY2
INHERIT=SHDC
ACTIVE.BOTH.SS=false;

So what you see is that I have inherited three command types, including the SHDC command type. But then I overrule the SS (SelfShadow) parameter by specifying a new value.

Frankly, this is all there is to creating command types. Janus already comes with a slew of command types that I personally have used in production and it forms the base of every other command type I've created thus far. You can build upon them, or build your own base. It's up to you.

'Vis' and 'Runtime' Directives
Because not all user-defined command types are directly used, they can be optionally hidden from the GUI. If you use the vis (visible) directive (value: true or false).

Furthermore, some command types are only mean to be used as a run-time command. In this case, specifying the runtime directive (value: true or false) will make the particular command type appear only in the run-time commands list.

[MyCommandType]
inherit=BTY
vis=true
runtime=false

'Test' Directive
A 'test' directive will tell Janus if the command type you are making is meant to be a test render command type. A test render command type is called when you execute a test render only. This is useful when you want to lower resolution, turn off GI, or set GI attributes to lower settings, or replace objects with their lower resolution counterparts whenever you do a test render. This is to facilitate a faster workflow for render-intensive, or heavy scenes.

Specifying 'true' (e.g. test=true) will make this command type visible in the test render dropdown box, as well as in the Preferences dialog. Unless you also specify 'vis=false' this command type will also be visible in the normal list of command types.

'Comment' Directive
A 'comment' directive allows you to describe your command type. Only one comment directive is allowed (the latest one read will be used). Janus appends these comments beside the actual command type in the C popdown in GUI.

__INHERIT__ SECTION
There may be situations where you would like to specify a command type on a per-project level. You can inherit a command type text file by creating a new section in your main Janus_CommandTypes.txt file called [__INHERIT__]. Add a file directive there pointing to a relative folder in a project file where you put your project command types. Example:

[__INHERIT__]
file=janus_configs/*.jct
vis=false
test=false

In the above, vis and test was specified so that this section does not appear in the popups. The file directive issues a relative path (this can also be an absolute) and uses a wildcard to gather all the text files that it expects to be definitions of commnad types. In this case, all extensions with .jct are collected and parsed for command types.

When you save new command types you will be given an option of saving to the global command types file, or to a project file.