/*
 * Copyright (c) 2009-2012 jMonkeyEngine
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *   may be used to endorse or promote products derived from this software
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.jme3.effect.influencers;

import com.jme3.effect.Particle;
import com.jme3.effect.ParticleEmitter;
import com.jme3.effect.shapes.EmitterShape;
import com.jme3.export.Savable;
import com.jme3.math.Vector3f;
import com.jme3.util.clone.JmeCloneable;

/**
 * An interface that defines the methods to affect initial velocity of the particles.
 * @author Marcin Roguski (Kaelthas)
 */
public interface ParticleInfluencer extends Savable, Cloneable, JmeCloneable {

    /**
     * This method influences the particle.
     * @param particle
     *        particle to be influenced
     * @param emitterShape
     *        the shape of it emitter
     */
    void influenceParticle(Particle particle, EmitterShape emitterShape);

    /**
     * This method clones the influencer instance.
     * @return cloned instance
     */
    public ParticleInfluencer clone();

    /**
     * @param initialVelocity
     *        Set the initial velocity a particle is spawned with,
     *        the initial velocity given in the parameter will be varied according
     *        to the velocity variation set in {@link ParticleEmitter#setVelocityVariation(float) }.
     *        A particle will move toward its velocity unless it is effected by the
     *        gravity.
     */
    void setInitialVelocity(Vector3f initialVelocity);

    /**
     * This method returns the initial velocity.
     * @return the initial velocity
     */
    Vector3f getInitialVelocity();

    /**
     * @param variation
     *        Set the variation by which the initial velocity
     *        of the particle is determined. <code>variation</code> should be a value
     *        from 0 to 1, where 0 means particles are to spawn with exactly
     *        the velocity given in {@link ParticleEmitter#setInitialVelocity(com.jme3.math.Vector3f) },
     *        and 1 means particles are to spawn with a completely random velocity.
     */
    void setVelocityVariation(float variation);

    /**
     * This method returns the velocity variation.
     * @return the velocity variation
     */
    float getVelocityVariation();
}