Semantics

A description of what semantics and hints are and how they can be applied to affect the behaviour of the application

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:

1. Traits provide a way of grouping metanodes by purpose

2. Property Semantics describe the purpose and behaviour of a particular property on a metanode

3. 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.

Supplementary Semantics 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 double property between 5 and 10, use range[0] = 5, range[1] = 10

• To limit a vec2 property between 1, 1 and 5, 5, use range[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 chapter 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.

---