Interface miMod(Module) – step 0022 – December 2009

1 Introduction

Currently modules are loaded statically.

Therefore they can be declared as prototype in any X3D file, only the frame author must know the URL of the file and the name of the prototype.

The module must forward the common parameters from the frame to the module coordinator

2 Static Embedding of Modules – Definition of miMod(Module)

The SRR framework requires following minimum interface from each module

The module author

• documents the position and orientation of the local coordinate system in relation to the module, to allow the frame author to create a surrounding <Transform> node.

• provides a meaningful default value for the module name

• allows the frame to change the module name, before it will be initialized

• takes the commParam parameter and forwards it to the module coordinator for initialization

3 Example of a Module for Static Embedding

<Scene>

<ProtoDeclare name='ThirdModule'>

<ProtoInterface>

<field accessType='inputOutput' name='commParam' type='SFNode'/>

<field accessType='inputOutput' name='moduleName' type='SFString' value='third'/>

</ProtoInterface>

<ProtoBody>

<ExternProtoDeclare name='SrrModCoord' url='"../srr/SrrModCoord.x3d" "http://members.chello.at/christoph.valentin/srr/SrrModCoord.x3d"'>

<field accessType='inputOutput' name='objType' type='SFString' value='SrrModCoord'/>

<field accessType='inputOutput' name='version' type='SFFloat' value='0.0022'/>

<field accessType='inputOutput' name='moduleName' type='SFString'/>

<field accessType='inputOutput' name='commParam' type='SFNode'/>

<field accessType='inputOutput' name='localTraceLevel' type='SFInt32' value='1'/>

<field accessType='inputOutput' name='activateRequest' type='SFBool' value='false'/>

<field accessType='inputOutput' name='deactivateRequest' type='SFBool' value='false'/>

<field accessType='outputOnly' name='activated' type='SFInt32'/>

<field accessType='outputOnly' name='modParam' type='SFNode'/>

<field accessType='inputOutput' name='srrModCoordModules' type='MFNode'/>

</ExternProtoDeclare>

<ExternProtoDeclare name='SrrModCoordTm' url='"../srr/SrrModCoordTm.x3d" "http://members.chello.at/christoph.valentin/srr/SrrModCoordTm.x3d"'>

<field accessType='inputOutput' name='objType' type='SFString' value='SrrModCoordTm'/>

<field accessType='inputOutput' name='version' type='SFFloat' value='0.0022'/>

<field accessType='inputOutput' name='modParam' type='SFNode'/>

<field accessType='inputOutput' name='localTraceLevel' type='SFInt32' value='1'/>

<field accessType='inputOutput' name='srrModCoordModuleIdx' type="SFInt32" value="-1"/>

<field accessType='outputOnly' name='initialized' type='SFNode'/>

<field accessType='inputOnly' name='registerVehicles' type='MFString'/>

</ExternProtoDeclare>

:

:

:

<Group DEF='PrototypeRootNode'>

<!-- *** The SrrTrains Module Coordinator -->

<ProtoInstance DEF='SrrModCoord' name='SrrModCoord'>

<fieldValue name="srrModCoordModules">

<ProtoInstance DEF='TrainManager' name="SrrModCoordTm"/>

</fieldValue>

</ProtoInstance>

<!-- *** Viewpoints of the module -->

<Viewpoint DEF='VP_platform' description='platform' position='-48 1.7 -30' orientation="0 1 0 -1.45"/>

<Viewpoint DEF='VP_overview' description='overview_third' position='-50 10 -20' orientation="0 1 0 -1.57"/>

<!-- *** Fix Avatar Container -> will be bound, when one of the fix viewpoints is bound -->

<ProtoInstance DEF='FixAvatarContainer' name='SrrAvatarContainer'>

<fieldValue name='objId' value='AvatarContainerFix'/>

</ProtoInstance>

<ROUTE fromField='isBound' fromNode='VP_platform' toField='set_bind' toNode='FixAvatarContainer'/>

<ROUTE fromField='isBound' fromNode='VP_overview' toField='set_bind' toNode='FixAvatarContainer'/>

<!-- *** Switchable light sources of the module -->

<PointLight DEF='Lamp1' location='-30 10 -20' radius='40' on='false'/>

<PointLight DEF='Lamp2' location='30 10 -20' radius='40' on='false'/>

<!-- *** Proxi Sensor to detect, when user enters the module and activate the module -->

<ProximitySensor DEF='Proxi' center='0 100 -20' size='100 200 40'/>

<!-- *** Landscape (buildt with GIMP and BLENDER) -->

:

:

:

<!-- *** Tracks and Turnouts (using the example track geometry v0.01) -->

:

:

:

</Group>

<!-- *** Script node for controller functions and diagnostic output -->

<Script DEF='ThirdModuleScript' directOutput="true" mustEvaluate="true">

<!-- miMod(Module) - Minimum Interface of the module (for the frame) -->

<field accessType='inputOutput' name='commParam' type='SFNode'/>

<field accessType='inputOutput' name='moduleName' type='SFString'/>

<!-- uiMod - use the user interface of the module coordinator -->

<field accessType='outputOnly' name='setCommParam' type='SFNode'/>

<field accessType='outputOnly' name='setModuleName' type='SFString'/>

<field accessType='inputOnly' name='modParam' type='SFNode'/>

<field accessType='outputOnly' name='activateRequest' type='SFBool'/>

<field accessType='inputOnly' name='activated' type='SFInt32'/>

<field accessType='outputOnly' name='registerVehicles' type="MFString"/>

<!-- initialize the SRR objects of the module -->

<field accessType='outputOnly' name='distributeModParam' type='SFNode'/>

<!-- interface to the functionality of the module (sensors, light sources, uiObj of SRR objects) -->

<field accessType='inputOnly' name='entering' type='SFBool'/>

<field accessType='inputOnly' name='isBound' type='SFBool'/>

<field accessType='outputOnly' name='setBind' type='SFBool'/>

<field accessType='outputOnly' name='lampOn' type='SFBool'/>

<!-- references to internal objects -->

<field accessType='inputOutput' name='getScript' type='SFNode'>

<Script USE="ThirdModuleScript"/>

</field>

<field accessType="inputOutput" name="tracer" type="SFNode">

<ProtoInstance DEF="Tracer" name="SrrTracer">

<fieldValue name="subsystem" value="MyThirdModule"/>

<fieldValue name="fileName" value="ThirdModule.x3d"/>

<fieldValue name="ssVersion" value="0100"/>

<fieldValue name="objId" value=""/>

<fieldValue name="instanceId" value=".MyController"/>

</ProtoInstance>

</field>

<IS>

<connect nodeField='commParam' protoField='commParam'/>

<connect nodeField='moduleName' protoField='moduleName'/>

</IS>

<![CDATA[

ecmascript:

// insert source here (see newECMAscript.js for example Script code)

function initialize()

{

setModuleName = moduleName;

tracer.instanceId = makeInstanceId(moduleName);

}

function commParam(Value)

{

setModuleName = moduleName;

tracer.instanceId = makeInstanceId(moduleName);

setCommParam = Value;

}

function makeInstanceId(Value)

{

return Value + '.MyController';

}

function modParam(Value)

{

tracer.modParam = Value;

tracer.eventReceived = new MFString(moduleName + '.uiMod,modParam','received modParam (module has been registered/deregistered/reregistered)');

if (Value.moduleIx < 0)

{

tracer.freeTextInfo = new MFString('Module Coordinator reported module index smaller than 0 -> display error status',

'error: ' + Value.commParam.errorStrings[Value.commParam.errorNo]);

}

else

{

tracer.freeTextInfo = new MFString('distributing module parameter (modParam) to all statically embedded SRR objects');

distributeModParam = Value;

registerVehicles = new MFString('wagon1;../ExampleVehicles/MyFirstWagon.x3d');

}

}

function entering(Value)

{

if (Value)

{

tracer.freeTextInfo = new MFString('User enters the module (proximity sensor) -> activate');

tracer.sendEvent = new MFString(moduleName + '.uiMod,activateRequest','value=true',

'sending activate request to ModCoord');

activateRequest = true;

}

}

function isBound(Value)

{

if (Value)

{

tracer.freeTextInfo = new MFString('one of the viewpoints of the module has been bound -> activate');

tracer.sendEvent = new MFString(moduleName + '.uiMod,activateRequest','value=true',

'sending activate request to ModCoord');

activateRequest = true;

}

}

function activated(Value)

{

tracer.eventReceived = new MFString(moduleName + '.uiMod,activated','value=' + Value,

'received activation pattern from ModCoord -> display');

if (Value & 32)

{

tracer.freeTextDebug = new MFString ('module has been deactivated');

tracer.freeTextInfo = new MFString ('switching light sources OFF');

lampOn = false;

}

if (Value & 8)

{

tracer.freeTextDebug = new MFString ('module has been activated by external request');

tracer.freeTextInfo = new MFString ('binding \'overview\' viewpoint');

setBind = true;

tracer.freeTextInfo = new MFString ('switching light sources ON');

lampOn = true;

}

else if (Value & 4)

{

tracer.freeTextDebug = new MFString ('module has been activated by own request');

tracer.freeTextInfo = new MFString ('switching light sources ON');

lampOn = true;

}

}

]]>

</Script>

<!-- provide module coordinator with basic values from miMod(module) -->

<ROUTE fromField='setModuleName' fromNode='ThirdModuleScript' toField='moduleName' toNode='SrrModCoord'/>

<ROUTE fromField='setCommParam' fromNode='ThirdModuleScript' toField='commParam' toNode='SrrModCoord'/>

<!-- Module coordinator delivers trace level for my tracer -->

<ROUTE fromField='localTraceLevel' fromNode='SrrModCoord' toField='localTraceLevel' toNode='Tracer'/>

<!-- module coordinator delivers modParam (after its initialization) to initialize SRR objects and tracer -->

<ROUTE fromField='modParam' fromNode='SrrModCoord' toField='modParam' toNode='ThirdModuleScript'/>

<!-- initialize static models -->

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='FixAvatarContainer'/>

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='TrackStation01'/>

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='Track001'/>

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='Track002'/>

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='Track003'/>

<ROUTE fromField='distributeModParam' fromNode='ThirdModuleScript' toField='modParam' toNode='PlatformSetupPoint'/>

<!-- proxi sensor reports entering the module -->

<ROUTE fromField='isActive' fromNode='Proxi' toField='entering' toNode='ThirdModuleScript'/>

<!-- a viewpoint of the module has been bound -->

<ROUTE fromField='isBound' fromNode='VP_platform' toField='isBound' toNode='ThirdModuleScript'/>

<ROUTE fromField='isBound' fromNode='VP_overview' toField='isBound' toNode='ThirdModuleScript'/>

<!-- script requests module activation from ModCoord -->

<ROUTE fromField='activateRequest' fromNode='ThirdModuleScript' toField='activateRequest' toNode='SrrModCoord'/>

<!-- ModCoord reports activation pattern of the module -->

<ROUTE fromField='activated' fromNode='SrrModCoord' toField='activated' toNode='ThirdModuleScript'/>

<!-- the modules reaction on de-/activation -->

<ROUTE fromField='setBind' fromNode='ThirdModuleScript' toField='set_bind' toNode='VP_overview'/>

<ROUTE fromField='lampOn' fromNode='ThirdModuleScript' toField='on' toNode='Lamp1'/>

<ROUTE fromField='lampOn' fromNode='ThirdModuleScript' toField='on' toNode='Lamp2'/>

<!-- register vehicles -->

<ROUTE fromField="registerVehicles" fromNode="ThirdModuleScript" toField="registerVehicles" toNode="TrainManager"/>

</ProtoBody>

</ProtoDeclare>

</Scene>