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.


No Results.

Getting StartedArchitectureBest PracticesHow ToAdvanced TopicsChangelogvrtree_cppCoreForeign Function InterfaceMetanodesMigrationsObserversPropertiesTreeUtilitiesAPI DefinitionsVR ExchangePluginsLua API