## GetMappingRule

### Introduced

v1.0

### Description

Gets a rule in a connection or value mapping template, or in a clip value map.
Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:
For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.
For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

### Scripting Syntax

    GetMappingRule( MappingTemplate, [Index], [From], [To], [Active], [PoseOffset] );

### Parameters

Parameter | Type | Description
--- | --- | ---
MappingTemplate | String | Mapping template or clip value map.
Index | Integer | Specifies the rule to modify. Rules are numbered starting at 1, but an index of 0 also refers to the first rule. Default Value: 0 (the first rule)
From | String | Returns the "From" part of the rule.
To | String | Returns the "To" part of the rule.
Active | Boolean | Gets the activeness of the rule.
Possible Values: | Description:
False | The rule is inactive.
True | The rule is active.
PoseOffset | Boolean | Gets the pose offset flag for the rule.
Possible Values: | Description:
False | The object is not pose offset.
True | The object is flagged for pose offset.

### Examples

#### VBScript Example

    ' This example illustrates various mapping template commands,
    ' for both connection and value mapping templates -- in particular
    ' how to create them and look at the data contained in them.
    NewScene , False
    ' Create some objects for our example.
    set oParent = CreatePrim( "Sphere", "MeshSurface", "Parent" )
    set oChild = CreatePrim( "Cone", "MeshSurface", "Child", oParent )
    posParams = "/kine.local.posx,kine.local.posy,kine.local.posz"
    ' Animate the sphere moving horizontally and the
    ' cone (child) moving down.
    SetPositionKey oParent, 1, -5, 0, 0
    SetPositionKey oParent, 50, 5, 0, 0
    SetPositionKey oChild, 1, 0, 0, 0
    SetPositionKey oChild, 50, 0, -2, 0
    ' Store an Action of this animation (on both objects).
    set oSource = StoreAction( , oParent & "," & oChild & posParams, 2, _
                            "Fun", True, 1, 50 )
    ' We want to map the animation to another "character", so we will
    ' use a connection mapping template.  CreateConnectionMap can look
    ' at identical hierarchies and automatically build an appropriate
    ' map.  (or you could build it yourself manually or using scripting)
    ' Here we'll build a hierarchy and use the auto-matching capability...
    set oParent2 = CreatePrim( "Cube", "MeshSurface", "Top" )
    set oChild2 = CreatePrim( "Cylinder", "MeshSurface", "Bottom", oParent2 )
    ' Translate it so we can demonstrate value mapping templates.
    Translate oParent2, 2, 5, 0, siAbsolute, siView, siObj, siXYZ
    Translate oChild2, 2, -5, 0, siAbsolute, siView, siObj, siXYZ
    ' Instantiate a clip driving the objects on which the animation was
    ' originally authored, for comparison.
    set oClip = AddClip( "Scene_Root", oSource, , , 1, "Original" )
    ' Now create the connection map so we can apply the original animation
    ' on the other hierarchy.  Also, create a value map which will build
    ' offset expressions using the pose differences between the objects.
    CreateConnectionMap oParent2, oParent, oCnxMap
    CreateValueMap oParent2, oParent, 3, 1, False, oValMap
    ' Instantiate a clip which uses the connection map to remap to the
    ' second set of objects.  Also use the value map to create a clip
    ' effect with the appropriate offset for the second hierarchy.
    set oClip = AddClip( "Scene_Root", oSource, , , 1, "Remapped", oCnxMap, oValMap )
    ' Let's take a look at the connection and value mapping templates
    ' that were created and used.
    DumpTemplateInfo oCnxMap
    DumpTemplateInfo oValMap
    ' Finally, a clip itself can be treated as a (value) mapping template.
    ' Let's look at one...
    DumpTemplateInfo oClip & ".actionclip"
    '==================================================
    ' Helper method to key an object somewhere at a given frame.
    '==================================================
    sub SetPositionKey( in_oObj, in_frame, in_posX, in_posY, in_posZ )
            Translate in_oObj, in_posX, in_posY, in_posZ, siAbsolute, siParent, siObj, siXYZ
            SaveKey in_oObj & posParams, in_frame
    end sub
    '==================================================
    ' Helper method to dump some mapping template info.
    '==================================================
    sub DumpTemplateInfo( in_Templ )
            ' Get the actual object referenced by name in the argument.
            set oTempl = GetValue( in_Templ )
            msg = "Template: " & oTempl.fullname & Chr(10)
            numRules = GetNumMappingRules( in_Templ )
            if oTempl.type = "actionclip" then
                    msg = msg & "(Clip acting as value map)" & Chr(10)
                    bSupportsActive = true
            else
                    bSupportsActive = false
            end if
            for i = 1 to numRules
                    GetMappingRule in_Templ, i, param, expr, active
                    msg = msg & Chr(9) & "Rule " & i & ": "
                    if bSupportsActive then
                            if active then
                                    msg = msg & "( active ) "
                            else
                                    msg = msg & "(inactive) "
                            end if
                    end if
                    msg = msg & param & " -> " & expr & Chr(10)
            next
            LogMessage msg
    end sub
    ' Running this script should log the following:
    ' ---------------------------------------------
    'INFO : "Template: Mixer.MappingTemplate
    '       Rule 1: Parent -> Top
    '       Rule 2: Child -> Bottom
    '"
    'INFO : "Template: Mixer.ValueMappingTemplate
    '       Rule 1: Top.kine.local.posx -> this + -3.000000
    '       Rule 2: Top.kine.local.posy -> this + 5.000000
    '       Rule 3: Top.kine.local.posz ->
    '       Rule 4: Bottom.kine.local.posx ->
    '       Rule 5: Bottom.kine.local.posy -> this + -8.000000
    '       Rule 6: Bottom.kine.local.posz ->
    '"
    'INFO : "Template: Mixer.Mixer_Anim_Track1.Remapped.actionclip
    '(Clip acting as value map)
    '       Rule 1: ( active ) Top.kine.local.posx -> this+-3.000000
    '       Rule 2: ( active ) Top.kine.local.posy -> this+5.000000
    '       Rule 3: ( active ) Top.kine.local.posz ->
    '       Rule 4: ( active ) Bottom.kine.local.posx ->
    '       Rule 5: ( active ) Bottom.kine.local.posy -> this+-8.000000
    '       Rule 6: ( active ) Bottom.kine.local.posz ->
    '"

### See Also

AddMappingRule CreateConnectionMap CreateValueMap DeleteMappingRule GetNumMappingRules SetMappingRule