Clarisse 4.0 SP3 SDK  4.0.0.0.3
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Introduction to CID syntax

Table of Contents

This topic introduces you to CID syntax which is extremely important if you are looking to extend Clarisse with custom modules. For more information on modules please refer to Declaring new modules in Clarisse.

What's CID?

CID pronounced seed stands for Class Interface Definition. CID is a special syntax created to simplify both definitions as well as implementations of new OfClass in Clarisse modules. Without CID, you would have to write tedious C++ lines and complex initializations that are mandatory when declaring custom classes.

Basic CID Structure

The structure of a CID is fairly simple as it uses the same syntax used by Clarisse when seriaziling objects and projects. The typical structure of a CID file looks like this:

class "my_class_name" "optional_base_class_name" {
//class properties
attribute_type "attribute_name1" {
//attribute properties
}
attribute_type "attribute_name2" {
//attribute properties
}
...
attribute_group "attribute_group_name1" {
attribute_type "attribute_name3" {
//attribute properties
}
attribute_type "attribute_name4" {
//attribute properties
}
...
}
attribute_group "attribute_group_name2"{
...
}
...
}

Class definition

A CID always starts by the class keyword wich defines the name of the class that is being defined in the CID. It can be optionnally be followed by the name of a base class it eventually inherits from.

Note
There can be only one class defined per CID and OfClass doesn't support multiple inheritance.

Attribute declaration

attribute_type in the example must be replaced by a keyword, picked from a list of supported attribute types, that defines the type and the visual representation of the attribute in the Attribute Editor.

For example, when attribute_type is set to the keyword distance[3], the CID defines an attribute of type GMathVec3d. Moreover, the keyword distance makes the Attribute Editor to automatically append the attribute value with the default distance unit system set in the preferences. This way the user has a direct feedback on the type of values he is manipulating.

Attribute type keywords are generated based on OfAttr::Type and OfAttr::VisualHint enumerations found in the file of_attr.h. The generation rule is pretty straightforward: keywords are the enum names lowercased with the enum type stripped of the name. For example OfAttr::TYPE_BOOL becomes bool while OfAttr::VISUAL_HINT_COLOR becomes color.

Here are the generic types without any particular user interface representation in the Attribute Editor:

keyword description
bool A boolean value
long A long value (signed)
double A 64-bit floating point value
file A string representing a file
string A string
reference A reference to another OfObject
object An embedded OfObject
curve A curve
action An action to a user defined callback. Please refer to Actions

Here are the more advanced types with specific user interface representation in the Attribute Editor:

keyword description
enum A type string value displayed in the UI as a list of predefined values (OfEnum)
color An array of 3 doubles represented as a RGB color in the UI
filename_save A file type value letting the user specify a save filepath.
filename_open A file type value letting the user specify an open filepath.
folder A string type value letting the user select folder path.
percentage A double type value representing percentage in the UI.
scale A double type value representing scale in the UI using the default scale unit.
distance A double type value representing distance in the UI using the default distance unit.
angle A double type value representing angle in the UI using the default angle unit.
frequency A double type value representing frequency in the UI using the default frequency unit.
time A double type value representing time in the UI using the default time unit.
frame A double type value representing frames
subframe A double type value representing subframes
second A double type value representing as seconds.
area A double type value representing an area.
watt A double type value representing Watts.
sample A long type value representing samples.
subsample A double type value representing subsamples.
sample_per_pixel A long type value representing sample(s) per pixel.
subpixel A double type value representing subpixels.
pixel A long type value representing pixel.
parent_reference A reference type value referencing an embedded object.
context A string type value referencing an OfContext.
l A double type value representing a luminance.
la An array of 2 doubles representing a luminance and alpha.
rgb An array of 3 doubles representing a RGB color.
rgba An array of 4 doubles representing a RGBA color.
gradient A curve type value represented as a color gradient.
memsize A double type value representing a memory amount.
tag A string type value representing tags while letting the user type the tag name.
tag_menu A string type value representing tags. Unlike tag, the user must choose its tag from a menu.
script A string type value representing a short string.
multiline A string type value representing a long string (multi line display).
group A reference type value representing a reference to a group.

Array and lists

It is possible to declare attribute with multiple values to represent arrays or lists. Both arrays and lists can be redimensionned. The difference between list and arrays is that items in a lists can be reordered. In general, arrays are used to represent contiguous data such as a color or a string whereas lists are used to represent a list of reference of OfObject. To declare an array you simply have to use the square bracket operator. For example, to declare an array of 3 double you need to write:

double[3] "my_double_array"

To declare a list you need to use the special keyword list followed by the type of attribute between greater and smaller than operators. For example, to declare a list of reference you need to write:

list<reference> "my_reference_list"
Warning
Not all type of attribute lists or arrays are supported by the Attribute Editor. In the event an attribute list or array is unsupported by the Attribute Editor, it doesn't get displayed.

Properties

The behavior of each attribute can be controlled by a set of properties. These properties can control, for example, the default value of the attribute used when the class is instantiated as well a valid range of values. Properties can define many other attribute behaviors such as if the attribute can be animated or even textured.

percentage "percentage" {
value 1
numeric_range yes 0 1
animatable yes
}

In this example, we've defined a new attribute labeled my_percentage with a default value of 1.0. The percentage keyword which acts as a display hint, makes sure the attribute is displayed as percentage (100%) in the Attribute Editor. The numeric_range property lets the attribute to process any input values to ensure they are always comprised between 0.0 and 1.0 [0%;100%]. This is extremely useful as it avoids to check the validity of incoming values. Finally, the animatable property sets that the attribute can be animated by the user.

property argument(s) description
doc description=stringSet the documentation of the attribute displayed as tooltip in the Attribute Editor
numeric_rangeactive=bool
min_value=scalar
max_value=scalar
Set the valid range of the attribute. Input values are always ensured to be in the specified ranged.
numeric_range_minactive=bool
min_value=scalar
Set the minimum valid value of the attribute. Input values are always ensured to be >= min_value.
numeric_range_maxactive=bool
max_value=scalar
Set the maximum valid value of the attribute. Input values are always ensured to be <= max_value.
ui_rangeactive=bool
min_value=scalar
max_value=scalar
Set the valid range of the attribute in the Attribute Editor when using mini sliders. When scrubbing the value, the value will be comprised between min_value and max_value. Note unlike numeric_range this property doesn't prevent the user to manually or programmatically input values outside the specified range.
ui_range_minactive=bool
min_value=scalar
Set a minimum valid value for the attribute in the Attribute Editor when using mini sliders.
ui_range_maxactive=bool
max_value=scalar
Set a maximum valid value for the attribute in the Attribute Editor when using mini sliders.
texturableactive=boolSet the attribute as texturable. A texturable attribute is an attribute that can be driven/modified by a texture.
animatableactive=boolSet the attribute as read only. A animatable attribute is an attribute that can be driven by a curve.
privateactive=boolSet if the attribute should be private. A private attribute is not meant to be edited by users. It is meant to be modified programmatically by the instance itself. Typically this kind of attribute can be used to store internal values.
saveableactive=boolSet if the attribute should be saveable (serialized). By default an attribute is saveable.
hiddenactive=boolSet if the attribute should be hidden from the user interface.
slideractive=boolSet if the attribute should display a mini slider next to the attribute value.
dg_activeactive=boolSet if the attribute should propagate dirtiness. When an attribute is set to active no no dirtiness propagation occurs when the attribute value is modified. This is typically useful for attributes that display internal values.
dg_cyclicactive=boolSet if the attribute of type reference should accept cycles in the dependency graph. This should be used with extreme caution.
dirtiness_pass_throughactive=boolWhen set to Yes, scene dependency graph notifications are not altered when passing through the attribute.
read_onlyactive=boolSet the attribute as read only. A read only attribute can't be modified by the user in the Attribute Editor.
shading_variableactive=boolSet if attribute accepts shading variables. This only makes sense on attributes of classes inheriting from the Texture class.
input dirtiness=stringSet the dirtiness mask of the attribute of type reference that is propagated when the reference object is modified. For example, a object referenced by the attribute can propagate the dirtiness "shading". This property allows you to mask this output dirtiness to another type such as "geometry". For more information on dirtiness type please refer to OfAttr::Dirtiness.
output dirtiness=stringSet the output dirtiness type propagated by the instance when the attribute is modified. By default, the instance propagates "all" but it can be narrowed to "shading" for example. For more information on dirtiness type please refer to OfAttr::Dirtiness.
filterclasses=list<string> Set a list of valid OfObject class for an attribute of type reference. For example, filter "Light" "Material" will let the user reference either lights or materials in the attribute. For attribute of type script, this allows to specify the language.
extensionextensions=list<string> Set a list of valid file extensions for the file browser used for attributes of type file. For example, extension "exr" "png" will set the file browser to support these specified extensions.
null_labellabel=stringSet the label displayed in the Attribute Editor when the attribute has the NULL value. The NULL value which is 0 or "" by default can redefined by using null_value keyword.
null_valuevalue=anySet the value that will be considered as NULL for the attribute.
presetname=string value=stringDefine a name and associate a value to it for attribute of type long. Please refer to Presets

Presets

Presets allows you to bound names to the numeric values of an attribute of type long. This is very useful to create lists of user friendly presets. For example, you may want to declare an attribute which displays to the user a list of shapes:

long "shapes" {
value 0
preset "Box" "0"
preset "Sphere" "1"
preset "Ellipsoid" "2"
preset "Tetrahedron" "3"
}

Overriding attribute properties in a subclass

Sometimes it can be useful to change the property of an attribute inherited from a parent class. For example, you may want to change the default value of an inherited attribute such as the attribute display_color defined in the class SceneItem. To do so, you can use the set keyword. In your subclass you just have to use the set keyword followed by the attribute name you wish to override and the block of properties you'd like to change.

set "display_color" {
value 11
}

Grouping

An attribute group is defined by a name and has no other mean than creating more user friendly interface by grouping logically set of attributes. The attribute_group keyword defines a set of attributes that will be grouped in the Attribute Editor. For example, you could create a group "Kinematic" on which you would declare 3 attributes translate, rotate, scale such as:

attribute_group "Kinematic" {
distance[3] "translate"
angle[3] "rotate"
scale[3] "scale"
}
Note
Attribute groups are optional. When attributes are not defined into a specific attribute group, attributes are displayed inside the General attribute group which is automatically created by default by the Attribute Editor.

Actions

Actions are a special type of attributes which are represented by a button in the Attribute Editor. An action is bound to a C++ callback. It is called each time the user presses the action button in the Attribute Editor or when invoked via the API.

Note
Actions can't rely on any specific arguments besides the OfObject instance and optional blind data (passed when invoked via the API) to the callback implementation inside the module.

An action is declared by the keyword action followed immediately by the name of the action. The action name must follow The identifier name standard (can't start by a digit, can't have white spaces...). For detailed information on action implementation please refer to Implementing actions in your modules

action "my_action"

Real world examples

Locator CID

The CID of the locator is very interesting as it is extremely simple. The CID of the locator doesn't define any attributes. It inherits all of them directly from the SceneItem class it derives from.

class "Locator" "SceneItem" {
#version 0.9
doc "The simplest scene item users can create. It is often used to create kinematic hierarchies."
}

Let's go through each line of this CID.

class "Locator" "SceneItem" {

A CID will always start by the class definition where you define the name of the new OfClass and the name of the OfClass it inherits its attributes from. In this example, we are declaring a new OfClass named Locator which inherits from the existing OfClass SceneItem. The last character { opens a declaration block like a XML tag would and is closed by } in line 4.

Note that groups can be nested.

#version 0.9

It indicates the module version. Module versions are saved into Clarisse's project files in order to keep versioning.

doc "The simplest scene item users can create. It is often used to create kinematic hierarchies."

This line defines a simple documentation string for the new module. Finally, we close the class block with:

}

Matte Material CID

class "MaterialMatte" "Material" {
#version 0.91
icon "../icons/object_icons/material_matte.iconrc"
doc "A material that define a matte color, with no light shading."
color "color" {
value 0.0 0.0 0.0
texturable yes
animatable yes
doc "Set the color of the material."
}
percentage "alpha" {
value 1
numeric_range yes 0.0 1
ui_range yes 0.0 1
texturable yes
animatable yes
doc "Set the opacity of the material."
}
long "alpha_mode" {
value 0
preset "Black hole" "0"
preset "Transparent" "1"
doc "Set how the transparency is handled. In black hole mode, no object is visible behind."
}
}

This more evolved CID defines some attributes and more properties than the Locator's one.

class "MaterialMatte" "Material" {
#version 0.91
icon "../icons/object_icons/material_matte.iconrc"
doc "A material that define a matte color, with no light shading."

These lines define a new material, the "MatteMaterial" that inherits from the "Material" OfClass. The icon keyword is used to specify a path to an iconrc file, a propriatary file, generated by icon2irc. icon2irc is a tool provided in the SDK allowing you to generate icons for your custom classes.

color "color" {
value 0.0 0.0 0.0
texturable yes
animatable yes
doc "Set the color of the material."
}

Here, a new attribute named "color" of type "color" is defined.

color "color" {

Defines the new attribute by specifying its type and its name. Then it opens an attribute block where all the properties related to this new attribute will be specified.

value 0.0 0.0 0.0

Defines the default value of the attribute. Being of type color, we specify 3 floating values.

texturable yes

Specifies that this attribute can be textured. Note: when the keyword texturable is missing, then the attribute cannot be textured.

animatable yes

Specifies that this attribute can be animated. Note: when the keyword animatable is missing, then the attribute cannot be animated.

doc "Set the color of the material."

Defines a simple documentation description for the attribute that will be displayed when hovering the mouse on the name of the attribute in the Attribute Editor.

}

Closes the attribute block.

percentage "alpha" {
value 1
numeric_range yes 0.0 1
ui_range yes 0.0 1
texturable yes
animatable yes
doc "Set the opacity of the material."
}

Here, the attribute "alpha" of type percentage is defined.

New keywords are used in lines 3 and 4.

numeric_range yes 0.0 1

Specifies the minimum (0.0) and maximum (1) value users can set through the UI or programmatically.

ui_range yes 0.0 1

Specifies the minimum (0.0) and maximum (1) value users can set in the Attribute Editor using the mini-slider next to the numeric field.

long "alpha_mode" {
value 0
preset "Black hole" "0"
preset "Transparent" "1"
doc "Set how the transparency is handled. In black hole mode, no object is visible behind."
}

The last attribute, "alpha_mode" of type "long" (long integer like in C++) is defined here. But this attribute defines presets in lines 3 and 4 meaning that in the Attribute Editor, this attribute is editable via a popup menu instead of a numeric field.

preset "Black hole" "0"

Defines the preset "Black hole" with value 0. This is the integer value that will be given to the attribute when uses choose this preset.

preset "Transparent" "1"

Defines the preset "Transparent" with value 1.

The identifier name standard

Because of langage limitations such as in Python, attributes, actions and class name can't be named with arbitrary names. To prevent any issues we've defined an identifier name standard which applies to attributes, actions and class name. Conforming to this simple rule will prevent any issues with Python or other scripting language bindings.

An identifier name can't start by a digit and must be composed of alphanumerical characters with the inclusion of the underscore.

Implementing actions in your modules

TODO

CID Full Syntax

Please find here a reference to CID syntax.

class <string> <string> [{
[#version <number>]
[category <string>]
    [icon <string>]
[abstract <yes|no>]
    [embedded_only <yes|no>]
[doc <string>]
[attribute_group <string> {
[doc <string>]
        [attribute_type|set <string> {
[doc <string>]
            [filter <string> [<string> ...]]
            [value <attribute_value> [<attribute_value> ...]]
            [preset <string> <string>
            [preset <string> <string>]
            [...]]
            [private <yes|no>]
            [hidden <yes|no>]
            [saveable <yes|no>]
            [texturable <yes|no> [<string>]]
            [animatable <yes|no>]
            [slider <yes|no>]
            [ui_range <yes|no> <scalar> <scalar>]
            [ui_range_min <yes|no> <scalar> <scalar>]
            [ui_range_max <yes|no> <scalar> <scalar>]
            [numeric_range <yes|no> <scalar> <scalar>]
            [numeric_range_min <yes|no> <scalar>]
            [numeric_range_max <yes|no> <scalar>]
            [dg_active <yes|no>]
            [dg_cyclic <yes|no>]
            [shading_variable <yes|no>]
            [dirtiness_pass_through <yes|no>]
            [input <string> [<string> ...]]
            [output <string> [<string> ...]]
            [context <string>]
            [group_filter <string>]
            [null_label <string>]
            [null_value <any>]
            [extension <string> [<string> ...]]
            [depends_on <string> [<string> ...]]
            [action <string>]
}]
}]
}]