Sym3Ripple

Represents a 2D ripple animation tied to a 3D location.

Constructor

let ripple = new Sym3Ripple();

Creates a ripple.

Modifying this ripple is only valid if control doesn’t return to the renderer. That is, only modify the ripple immediately after creating it. If the context in which you did ends and control is returned to sym3.js (for example, you return from a callback), and then try and modify the ripple, an Error will be thrown.

If a ripple animation is being played from a prior construction at the time of this ripple’s construction, the previous ripple will stop; only one ripple animation will play at a time.

Sym3Ripple.Position

let ripple = new Sym3Ripple();
console.log(ripple.Position);
ripple.Position = new Sym3Vec3(0, 0, 0);

Gets and sets the 3D position that this ripple is associated with.

The location sets the very center of the animation.

Ripples will always display over a 3D point. For example, if you set the position of a ripple to the location of a fixed piece of equipment, as you move the camera around, the ripple will remain over that equipment.

Sym3Ripple.Color

let ripple = new Sym3Ripple();
console.log(ripple.Color);
ripple.Color = new Sym3Color(1.0, 0.0, 0.0, 1.0);

Gets and sets the color of the ripple.

This color is used at the center of the animation; when the ripple first appears.

As the animation progresses, the color will become more transparent (the alpha will fade to zero).

Sym3Ripple.Frequency

let ripple = new Sym3Ripple();
console.log(ripple.Frequency);
ripple.Frequency = 1.34;

Gets and sets the frequency of the ripple animation, in hertz.

Ripples will be generated at this rate per second.

Sym3Ripple.Duration

let ripple = new Sym3Ripple();
console.log(ripple.Duration);
ripple.Duration = 3.42;

Get and set the time it takes for one ring to reach its maximum radius, in seconds.

Note that this is not the duration of the animation. TotalDuration is the property that controls how long the ripple animation takes.

Sym3Ripple.TotalDuration

let ripple = new Sym3Ripple();
console.log(ripple.TotalDuration);
ripple.TotalDuration = 1.523;

Get and set the time it takes for the animation to complete, in seconds.

The animation will take a little longer than this to completely fade; once the animation is complete, rings stop being produced and existing rings fade away.

Note that the property that controls how long it takes for an individual ring to disappear is Duration.

Sym3Ripple.Thickness

let ripple = new Sym3Ripple();
console.log(ripple.Thickness);
ripple.Thickness = 4.0;

Get and set the width of an individual ring; the distance between the inner and outer border, in pixels.

This remains constant over the animation.

Sym3Ripple.Radius

let ripple = new Sym3Ripple();
console.log(ripple.Radius);
ripple.Radius = 5.1;

Get and set the radius of a ring, in pixels.

The radius is measured from the center of the animation, to the inner border of the ring when its animation is complete. That is to say, the radius starts small and expands to the value set here, over the length of time set as the ripple’s duration.

Example

CenterOn is a function that, given an equipment name, color, radius, and duration, will center the given equipment, set the layer the equipment is on to visible if it is not, and then create a ripple on the equipment.

// Return the layer that an equipment is on, or null.
function GetEquipmentLayer(equipment)
{
    let layers = SYM3.GetLayerNames(); // An array with every layer's name as a string.
    for (let i = 0; i < layers.length; ++i)
    {
        // An array with every piece of equipment on the given layer.
        let equipments = SYM3.GetEquipmentList(layers[i]);
        // If the layer has `equipment`, then return the layer name.
        if (equipments.indexOf(equipment) > -1)
            return layers[i];
    }
    return null;
}

// If the given layer is not visible, make it visible.
function MakeVisible(layer)
{
    if (!SYM3.GetLayerEnabled(layer))
        SYM3.SetLayerEnabled(layer, true);
}

function CenterOn(equipment, color, size, duration)
{
    let layer = GetEquipmentLayer(equipment);
    if (layer === null)
        return; // We don't know this equipment; do nothing.
    MakeVisible(layer); // Ensure that the equipment's layer is visible.

    // Move the equipment to the center of the screen.
    SYM3.CenterEquipment(equipment);

    // Create the specified ripple. The animation won't start until we return from this function.
    let position = SYM3.GetEquipmentPosition(equipment);
    let ripple = new Sym3Ripple();
    ripple.Position = position;
    ripple.Color = color;
    ripple.Radius = size;
    ripple.TotalDuration = duration;
}

/* Center on BasicShape2, generate a red ripple that expands to a radius of
 * 100 pixels, and lasts a total time of two seconds.
 */
CenterOn("BasicShape2", new Sym3Color(1.0, 0.0, 0.0, 1.0), 100.0, 2.0);