Control Link Technical Guide
Section 4 - SUBCLASSES OF <CONTROL LINK>
4.1 <Control Link> Subclasses That Turn On and Off
4.1.1 <Light Source Control Link>

<Light Source Control Link> provides control over the active_light_value field of a <Light Source>. This allows the consuming system to turn the <Light Source> on and off at will.

4.1.2 <Light Rendering Properties Control Link>

<Light Rendering Properties Control Link> provides control over the active_value and candela_value field values of the target <Light Rendering Properties> instances. This allows the user to control whether the target is 'on' or 'off', and if it's on, how bright it is. In addition, if the user allows the candela_value field to vary, <Light Rendering Properties Control Link> can specify constraints on the upper and lower limits of the candela value, so that there are limits on the maximum and / or minimum brightness. The user is not required to provide control over all 4 fields, however. If any of the link fields is zero, then the corresponding target field is not controlled.

4.1.3 <Sound Instance Control Link>

<Sound Instance Control Link> provides control over the active_sound_value field of a <Sound Instance>. This allows the consuming system to turn the <Sound Instance> on and off at will.

4.2 <State Control Link>
4.2.1 Overview

A state-related aggregation represents something that can assume multiple states; each branch of the aggregation represents a particular state. The state-related aggregation object itself specifies the state being describe with its state_tag field. The state is one of a special set of EDCS Attributes that are designated as "state applicable". Each branch of the aggregation has a <State Data> link object, specifying the value of the state associated with that branch.

4.2.2 Applying <State Control Link> to a <State Related Geometry>

Consider a specific building represented by a <State Related Geometry> instance. The data provider in this example has chosen to model 4 damage states: 0% damaged, 25% damaged, 50% damaged, and 100% damaged (totally destroyed).

state_tag EAC_GENERAL_DAMAGE_FRACTION
active_state_value 0%

This indicates that the 'default' state of the aggregation is 0% damage, that is, completely undamaged. The branches' <State Data> link objects have the following field values (meanings given in the bottom row).

state_value 0% 25% 50% 100%
meaning building's OK some damage heavy damage a little pile of rubble

Generally speaking, any state-related aggregation should be produced with an appropriate <State Control Link> component. After all, if a data provider has created an object that can assume one of multiple states, it only seems reasonable to provide the mechanism to change between states; why would a producer go to the trouble of representing multiple states of an object if only the default state could ever be used? Consequently, the building example needs a <State Control Link> to allow the use of states other than the default of 0% damage.

The <State Control Link> component controls the active_state_value by providing a connection between it and the controlling <Expression>, so that the active_state_value changes to specify which branch of the aggregation is currently active. Since active_state_value is the only controlled field in a state-related aggregation, the <State Control Link> should have exactly 1 <Expression> component, and therefore its expr_index field value would be 1.

expr_index 1
mismatch_behaviour SE_STMISMBEH_LAST

In this example, the <Expression> is a <Variable>, so that whatever value is plugged into the <Variable> when the <State Related Geometry> is instanced is then fed into the active_state_value.

meaning {SE_ELEMTYPCOD_VARIABLE, SE_VARCOD_ACTIVE_STATE_VALUE}
value_unit EUC_UNITLESS
value_scale ESC_UNI
value_type EDCS_AVT_REAL
description {SE_LOCALE_DEFAULT, 12, "damage state"}
runtime_label {SE_LOCALE_DEFAULT, 0, ""}

Suppose that a value of 25% is supplied to the <Variable>. The aggregate then changes state to 25% damage. Then more damage is done, so that the damage is updated to 45%. This presents a problem, because the data provider has specified each branch with a single matching value, and 45% is not covered by any of the branches. At this point, the mismatch_behaviour of the <State Control Link> comes into play. Since its value is SE_STMISMBEH_LAST, the aggregation will remain in the 25% damage state.

There are two other possible choices for mismatch_behaviour, but they are not appropriate for this example. SE_STMISMBEH_DEFAULT would have reset the aggregate to its default state (that provided by the original unmodified active_state_value), namely, 0% damage. The effect would be that 45% damage would magically appear to return the building to its intact state, as for that matter, would 99% damage, or any other value not covered by the branches of the aggregation. This would seem rather peculiar to the end user. The other possible choice, SE_STMISMBEH_NONE, acts as an 'off' state. The building would seem to disappear completely if none of the branches matched, then reappear when a matching value occurred. If that had been specified, 5% damage would make the building disappear from sight, but 25% damage would make it reappear, making life rather bizarre for the end user.

4.3 Customizing or Dynamically Changing Appearance
4.3.1   <Control Link> Subclasses for the Subclasses of <Colour Data>

<CMY Colour Control Link>, <HSV Colour Control Link>, and <RGB Colour Control Link> serve exactly the same purposes for their respective colour models. An understanding of the operation of any of the three is an understanding of the principles underlying the operation of all three. Consequently, this section will describe the operation of <RGB Colour Control Link> only, with the understanding that the explanation applies to the other two classes in principle.

<RGB Colour Control Link> provides control over the red, green, and blue fields of the target <RGB Colour> instances. A data provider is not required to provide control over all three fields. If any of the link fields within an <RGB Colour Control Link> instance is zero, that indicates that the corresponding target field is not controlled.

<RGB Colour> instances within the context of a <Colour Table> shall not have <RGB Colour Control Link> components, because a <Colour Table> does not provide an <Interface Template> to allow values to be supplied for <Variable> instances. Data consumers need only concern themselves with <RGB Colour Control Link> instances in the context of <Model> and <Environment Root> instances, and even in that case primarily with the former rather than the latter.

A data provider may wish to provide control over the colour of a <Model>, so that every <Geometry Model Instance> of that <Model> can be given a different colour, allowing the user of the <Model> to vary the appearance of model instances without being forced to replicate many <Model> instances that differ only in colour. As another example, a <Model> representing a car may be designed for an environment in which thermal colours are a consideration. In this case, the user might need the ability to change the colour of the car dynamically, as the engine heats up from a cold start or as the engine cools down after being shut off.

4.3.2 <Translucency Control Link>
<Translucency Control Link> provides control over the translucency_value field of a <Translucency> instance. This allows such visual effects as fading in puddles based on the precipitation rate.
4.3.3   <Texture Coordinate Control Link>

<Texture Coordinate Control Link> provides control over the s and t fields of a <Texture Coordinate>. The producer is not required to provide control over both fields. If either of the link fields within a <Texture Coordinate Control Link> instance ( s_expr_index or t_expr_index) is zero, that indicates that the corresponding target field is not controlled.

4.4 <Control Link> Subclasses for Table Indices
4.4.1   <Proprty Set Index Control Link>

<Attribute Set Index Control Link> provides control over the index field value of the target <Property Set Index> instances. For example, the appearance of a tree canopy varies according to the season of the year, so a data provider may choose to provide the ability to apply different texture maps and colours to a representation of a tree canopy to represent its appearance in different seasons. This can be achieved by providing an <Property Set Table> containing a different <Property Set> for each season of the year, which in turn specifies appropriate <Colour> and <Image Mapping Function> instances. The aggregate representing the tree canopy is provided with an <Property Set Index> with a component <Property Set Index Control Link>, to allow the user to change the <Property Set Index> index field to select the appropriate <Property Set> for a given time of year.

4.4.2   <Colour Index Control Link>

<Colour Index Control Link> provides control over the index and intensity_level fields of the target <Colour Index> instances. A data provider is not required to provide control over both field values. If either of the link fields within a <Colour Index Control Link> instance is zero, that indicates that the corresponding target field is not controlled.

4.4.3   <Property Table Reference Control Link>

<Property Table Reference Control Link> provides control over the index_on_axis field of the target <Property Table Reference> instances. This allows the user to specify different N-1 dimensional 'slices' of the N-dimensional <Property Table> that is referred to by a given target <Property Table Reference> instance.

For example, consider a <Polygon> instance that specifies the electromagnetic properties of its surface material by a <Property Table Reference> component. If the <Property Table Reference> has a <Property Table Reference Control Link>, its index_on_axis field value can be changed at will, allowing the user to change the electromagnetic properties of the <Polygon> as a result.

4.5 <LSR 3D Location Control Link>

<LSR 3D Location Control Link> provides control over the u, v, and w fields of the coordinate fields of the target <LSR 3D Location> instances. Data providers are not required to provide control over all three fields. If any of the link fields within an <LSR Location 3D Control Link> ( u_expr_index, v_expr_index, or w_expr_index) is zero, that indicates that the corresponding target field value is not controlled.

For example, consider an <LSR 3D Location> in a <Model> representing a building, where the location represents a point at the foundation of the building. In this case, the data provider wishes to be able to conform each instance of the <Model> to the terrain on which it is instanced, so that the bottom of the building rests on the terrain, regardless of whether the terrain is flat or hilly. The <LSR 3D Location> is provided with an <LSR 3D Location Control Link> that specifies zero for the u and v values of the target, but a controlling <Variable> for the w value.

4.6   <Reference Vector Control Link>

<Reference Vector Control Link> provides control over the unit_vector field values of the target <Reference Vector> instances. Data providers are not required to provide control over all three entries of the unit vector. If any of the link fields within <Reference Vector Control Link> ( v0_expr_index, v1_expr_index, and v2_expr_index) is zero, that indicates that the corresponding target is not controlled.

One possible use of a <Reference Vector Control Link> is to specify the normal vector of a <Polygon> instance. Another possible use is to control a <Reference Vector> of type SE_REF_VEC_TYP_LIGHT_DIRECTION, to allow the user to control the direction of the light.

4.7 Motion: <Control Link> Subclasses for Subclasses of <LSR Transformation Step>
4.7.1 <Rotation Control Link>

<Rotation Control Link> provides control over the angle field values of the target <Rotation> instances. In addition, <Rotation Control Link> is specialized to provide control over the upper limit and / or lower limit of the rotation angle, although a data provider is not required to provide control over all three target fields. If any of the link field values within a <Rotation Control Link> instance is zero, then the corresponding target field value is not controlled.

An example of the use of <Rotation Control Link> is to specify physical constraints on the rotation of a moving part (as well as to allow the part to rotate in the first place). Consider a robot with a jointed 'arm', where the joint acts like a human elbow: the 'forearm' can be rotated for a range of 90 degrees about the axis of the elbow joint, but there are upper and lower limits to the angle of rotation where the joint would have to be broken to permit any further rotation.

An example where rotation might be provided without limits can be provided by considering a weathervane. A weathervane can rotate about its axis, but has no physical limits on its rotation, so it does not have to be modelled with constraints on the amount of rotation.

As an example, consider a <Model> of a rotating weather vane, such that the weather vane turns to match the wind direction. The <Model> therefore has an <LSR Transformation> on its top-level geometry to represent the rotation - that is, the <LSR Transformation> has a <Rotation> component.

However, the rotation angle is determined by the wind direction, which is not a fixed value, and is not the same at different locations in the world. Each instance of the weather vane needs to have an independent rotation. Consequently, the <Rotation> has a <Rotation Control Link> component that changes the angle value of the <Rotation> to match the wind direction. The controlling <Expression> of the <Rotation Control Link> is therefore a <Variable> with a meaning of SE_VARCOD_ROTATION_ANGLE. This <Variable> is associated by the <Model>'s <Interface Template> so that each instance of the model can plug in the appropriate value, in this case the wind direction at that point.

4.7.2   <Translation Control Link>

<Translation Control Link> provides control over the translation_amount field of the target <Translation> instances. Specifically, <Translation Control Link> is specialized to provide control over the amount of translation, together with control over the lower limit of that amount and / or control over the upper limit. A data provider is not required to provide control over all three field values. If any of the link field values within a <Translation Control Link> instance is zero, that indicates that the corresponding target field is not controlled.

An example of the use of a <Translation Control Link> is to specify physical constraints on the motion of a moving part. For instance, a building <Model> may contain an elevator that can move up or down an elevator shaft. The elevator has physical limits on how far it can translate up or down without smashing into the top of the shaft or plunging through the bottom, so it requires upper and lower limits on the amount of translation.

As another example, consider a robot with an 'arm' that can be extended or retracted from its 'body'. The arm has physical limits on how far it can be extended without 'floating' away from the robot's body, and how far it can be retracted into the robot without 'breaking' the model. Consequently, it requires upper and lower limits on the amount of translation.

4.7.3   <Scale Control Link>

<Scale Control Link> provides control over the scale_amount field of the target <Scale> instances. As with <Control Links> for translation and roation, <Scale Control Link> is specialized to provide control over the upper and lower limits of the scale, as well as the scale itself.

4.8   <Polygon Control Link>

<Polygon Control Link> provides control over some of the individual flags within the polygon_flags fields of the target <Polygon> instances: hat test, collidible, invisible, and laser range finding. Since polygon_flags is a set rather than a single value, in which each flag may be set to on or off, each flag that can be controlled has a corresponding link field in <Polygon Control Link>, and specifies a controlling <Expression> that is evaluated as a boolean, to determine whether the corresponding flag should be set or unset. Note that only some of the flags may be controlled, but this is only because there have been no user requirements to control any of the other flags. If any such requirements arise, the SEDRIS team would be happy to consider any change requests.


Return to: Top of this Page