Semantics
In the context of Visionary Render, Semantics can be considered as descriptions attached to nodes or metanodes, which provide information to Visionary Render regarding how to interpret the node and present it to the user.
There are three categories of semantics:
- Traits - provide a way of grouping metanodes by purpose
- Property Semantics - describe the purpose and behaviour of a particular property on a metanode
- GUI Hints - affect the appearance of a node or property in the Visionary Render user interface
Traits
Traits are a bit like a type, in that they describe vaguely what a metanode is for, but different because multiple metanodes can be given the same trait in order to group them.
Trait names are arbitrary - a plugin may invent new traits and apply them to whichever metanodes it defines. It would do this using VRAddTrait when defining the metanode.
The metanodes defined by the Visionary Render application make use of a number of standard traits, which a plugin may also use in order to group its metanodes with the application-defined ones.
Standard Traits
| Trait Name | Description |
|---|---|
Trait_Texture | Node represents some kind of texture data |
Trait_Material | Node represents some kind of material |
Trait_Model | Node represents some kind of model |
Trait_Viewport | Node represents some kind of viewport |
Trait_Mesh | Node represents some kind of mesh |
Trait_AttributeTable | Node represents an 2xN attribute table |
Trait_List | Node represents some kind of container node, like a Meta_LightList |
Trait_GUIComponent | Node represents some kind of GUI object such as a button or panel |
Trait_GUIResource | Node represents some kind of GUI resource such as a style applied to a Trait_GUIComponent |
Trait_PanelStyle | Node represents some kind of panel style |
Trait_ButtonStyle | Node represents some kind of button style |
Trait_LabelStyle | Node represents some kind of label style |
Trait_MarkerStyle | Node represents some kind of marker style |
Trait_Caption | Node represents some kind of tree view caption |
Property Semantics
Property semantics contain a basic description of what a property is intended to be used for. For example, is it a colour, or a file.
When defining a metanode, property semantics are applied automatically when using functions such as VRAddPropertyVec2iRange, as well as when applying special conditions to properties such as VRSetPropertyReadOnly.
Semantics can also be applied to node instances by creating a PropSemantics node as a child of the target node, naming it after the property you wish to affect. You then have full control over all of the semantics for that instance's property.
The Visionary Render user interface responds to semantics when generating property editors for node properties and settings values. There are a number of built in property types that can be specified on the semantics node:
| Semantic Name | Description |
|---|---|
colour | Editors of this property display the colour wheel for vec3 and vec4 properties |
custom | Editors of this property display the value of the CustomText and CustomText2 GUI Hints as captions of up to two elements for vec2 properties |
image | Editors of this property display the image picker and preview control for string properties, providing a file browser and image stats of the loaded image, and populating the string property with the absolute path to the picked file |
file | Editors of this property display the file picker controls for string properties, and populates the string property with the absolute path to the picked file |
filesave | Editors of this property display the file picker controls (with "save" captions) for string properties, and populates the string property with the absolute path to the picked file |
dir | Editors of this property display the directory picker controls for string properties, and populates the string property with the absolute path to the picked directory |
slider | Editors of this property display a slider/spin box pair of controls for floating point number properties |
logslider | Editors of this property display the same control as slider except it also applies a base 10 logarithmic scale |
log2slider | Editors of this property display the same control as slider except it also applies a base 2 logarithmic scale |
rect | Editors of this property display a rectangle control with "Position" and "Size" editors for vec4 properties |
matrix | Editors of this property display a 4x4 grid of values for raw matrix editing of a mat4 property |
2dmatrix | Editors of this property display "Offset", "Scale", and "Rotation" controls for a mat4 property that is intended to be interpreted in 2D space |
stream | Editors of this property display the file picker controls for string properties but do not check whether the file exists, allowing entry of URIs to remote resources |
singlelinetext | Editors of this property provide a single-line string input for string properties (the default control for string properties is a multi-line edit control) |
font | Editors of this property provide a dropdown containing system fonts for a string property |
luacode | Adding this to a string property allows it to be opened and edited by the script editor in Visionary Render, in Lua mode. Only the first property with this hint is used. |
glslcode | Adding this to a string property allows it to be opened and edited by the script editor in Visionary Render, in GLSL mode. Only the first property with this hint is used. |
Additional Properties
There are some additional properties on a PropSemantics node that supplement some of these types:
Filter
The filter can contain differing formats of information depending on the semantic type
| Property or Semantic | Format |
|---|---|
image,file,filesave,stream | Windows-style format string with nulls replaced by pipe (e.g. Windows Media Files|*.wmv|AVI Files|*.avi). Controls the types of files selectable in the file browser dialog |
link | Comma-separated list of metanode names (no version suffix) or traits (e.g. Assembly,Trait_Texture). Controls the types of nodes able to be linked to by this link property. |
mat4 (no type override) | Colon separated list of transform sections to hide, out of pos, rot, and scale (e.g. pos:scale to show only the rotation controls) |
Range
The range can provide hints about the usable limits of the property, up to a maximum property size of 4 doubles. The range property itself is 8 doubles wide, and the min/max value should be packed in starting at index 0 according to the size of the target property.
For example:
- To limit a single
doubleproperty between 5 and 10, userange[0] = 5, range[1] = 10 - To limit a
vec2property between 1, 1 and 5, 5, userange[0] = 1, range[1] = 1, range[2] = 5, range[3] = 5 - and so on
Read Only
To specify that the property should not be editable (controls are usually greyed out when displayed in the editor), set the ReadOnly property on the semantics node to false.
GUI Hints
GUI Hints provide a more detailed set of information for the user interface, for example, captions, tooltips, help topics, group layouts, etc.
To add these additional hints to a property, use the VRAddGuiHintDouble (and related) functions in a metanode definition, or create a GuiHints node on a node instance to affect only that instance of the node.
This table lists all available hints, as well as the type, so that the correct VRAddGuiHint function can be used to apply it:
| Hint Name | Type | Description |
|---|---|---|
Step | double | Specifies the step size to use for spin boxes (truncated when applied to int or float spin boxes). A value of 0 means no step override, in which case the application default step sizes are applied. |
Precision | int | The number of decimal places displayed in floating point spin boxes. Any negative value means no precision override, in which case the application default precision settings are applied. |
Prompt | string | A string to display while prompting the user for input on file or directory pickers (see semantics types) |
Tooltip | string | A string to display when the user hovers over the property editor caption |
HelpTopic | string | The name of the section in the help document describing how to use this property. This is triggered using the context sensitive help feature. |
Caption | string | A string to display next to the property editor. If no caption is specified, the raw property name is displayed. |
CustomText | string | The first custom text (for semantic type custom) |
CustomText2 | string | The second custom text (for semantic type custom) |
Group | link | (advanced) Link to a group descriptor node that this property should be a member of (see next subsection) |
NoGui | bool | If true, the GUI system should not create any controls for this property at all, effectively hiding it. This is analogous to calling VRSetPropertyInternal |
About | string | A string containing even more detailed information that would not fit in a tooltip. Currently only the settings window is capable of displaying this, and will only do so for setting sub-categories (tab roots) |
ImageFilename | string | The name of an icon file relative to the data directory to display next to this property |
CreateNewEnabled | bool | (link properties) Instructs the link picker control to use the contents of the filter semantic to add a menu item for creating new nodes of any filtered type and automatically linking to them. |
SearchPaths | int | (link properties) Specifies how the link picker control decides which nodes to list in its dropdown (see below) |
Search Paths
The search path property on a GuiHints node is used for controlling where link pickers get their dropdown contents from. These dropdowns are always subject to any filter semantics applied, to control which types of nodes are listed.
| Value | Name | Description |
|---|---|---|
| 0 (default) | Siblings | The dropdown lists direct siblings of the node currently in the link property. If there is no link, the dropdown is empty. |
| 1 | Libraries | The dropdown lists the contents of the entire libraries tree |
| 2 | LibrariesSystemLibs | The dropdown lists the contents of the entire libraries tree as well as the contents of the SystemLibs node in the developer tree (which contains standard library objects) |
Dropdown Menus
Some properties make more sense when presented to the user as a dropdown control (usually int properties).
This is done by adding GuiOptionHint nodes as children of the hints node. These nodes have the following properties:
| Property | Type | Description |
|---|---|---|
Value | int | The value of the dropdown option. This is the value applied to the property when the option is selected. |
Caption | string | The caption for the option. This is the text displayed in the dropdown menu list. |
Tooltip | string | The description of the option, to be displayed when the user hovers over the option in the dropdown menu list. |
ImageFilename | string | The name of an icon file relative to the data directory to display next to this option in the dropdown menu list. |
The presence of one or more GuiOptionHint children automatically triggers the creation of a dropdown control when the application presents the property editor for this property.
Grouping
Sometimes a number of properties can depend on the state of another to be relevant. For example, a system may have an "Enabled" property, and a selection of other properties that have no effect unless the system is enabled.
To deal with this, properties can be grouped by creating a GuiGroupHint. Any properties that should exist in this group should link to this node in their GuiHints::Group property. Groups may themselves also exist inside other groups, creating nested hierarchies of expandable property grids.
A group hint has the following properties
| Property | Type | Description |
|---|---|---|
VisibleCondition | string | Condition under which this group should be visible. This is the string interpretation of the property or setting that should result in the group being visible. For example, "true", when the group node is a child of the YourSystem.Enabled property hints node will display the group when that property is enabled. It may also separate multiple conditions with a | (interpreted as "OR"). |
ExpandCaption | string | OR, instead, a caption to display on a button allowing the user to manually expand and collapse the group. This is mutually exclusive with VisibleCondition. A group may only specify one or the other. Groups using manual expanders should be added to the node's root GUI Hints node rather than to a specific property hint. |
Group | link | Link to a parent group hint node, if this group is nested inside another group |
ExpandedByDefault | bool | For groups with manual expand controls, this specifies whether the group should be initially expanded when the GUI is generated. |
Ordering
By default, the property controls are generated in the order that they appear on the metanode. This may not always be desirable, so there is a GuiOrderHint node that links to a specific property in the metanode definition tree (or in the case of settings, a particular setting node). Order hints may also link to group hint nodes, and group hints may themselves contain order hints.
When generating the properties interface, the application iterates GuiOrderHints first, displaying the properties in this order, before continuing on to any remaining properties in their original order.
The order hints should be added as children of a node or metanode specific GuiHints node, rather than that of a specific property. For node instances, this should be a child of the node with the specific name "GuiHints" (case sensitive). For metanode instances, it should be a child of the MetaNode node - the name of the node does not matter in this case.
References
In some cases, it would be inefficient to duplicate the data on hints and semantics nodes for multiple node instances of the same type. If node instance hints and semantics are required on multiple instances, it is better to add the GuiHints and PropSemantics nodes to a single instance, and then use PropSemanticsLink and GuiHintsLink nodes on the remaining instances to link to the original data.