//
// $Id$
//
// Narya library - tools for developing networked games
// Copyright (C) 2002-2005 Three Rings Design, Inc., All Rights Reserved
// http://www.threerings.net/code/narya/
//
// This library is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License as published
// by the Free Software Foundation; either version 2.1 of the License, or
// (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

package com.threerings.media.effects;

import java.awt.AlphaComposite;
import java.awt.Composite;
import java.awt.Graphics2D;

/**
 * Handles the math and timing of doing a fade effect in a sprite or animation.
 */
public class FadeEffect
{
    public FadeEffect (float alpha, float step, float target)
    {
        // save things off
        _startAlpha = _alpha = Math.max(alpha, 0.0f);
        _step = step;
        _target = Math.min(target, 1.0f);

        // create the initial composite
        _comp = AlphaComposite.getInstance(AlphaComposite.SRC_OVER, _alpha);
    }

    public void init (long tickStamp)
    {
        _initStamp = tickStamp;
    }

    public boolean finished ()
    {
        return (_startAlpha < _target) ?
            (_alpha >= _target) : (_alpha <= _target);
    }

    public float getAlpha ()
    {
        return _alpha;
    }

    public boolean tick (long tickStamp)
    {
        // figure out the current alpha
        long msecs = tickStamp - _initStamp;
        float alpha = _startAlpha + (msecs * _step);
        if (alpha < 0.0f) {
            alpha = 0.0f;
        } else if (alpha > 1.0f) {
            alpha = 1.0f;
        }

        if (_alpha != alpha) {
            _alpha = alpha;
            _comp = AlphaComposite.getInstance(AlphaComposite.SRC_OVER, _alpha);
            return true;
        }

        return false;
    }

    public void beforePaint (Graphics2D gfx)
    {
        _ocomp = gfx.getComposite();
        gfx.setComposite(_comp);
    }

    public void afterPaint (Graphics2D gfx)
    {
        gfx.setComposite(_ocomp);
    }

    /** The composite used to render the image with the current alpha. */
    protected Composite _comp;

    /** The composite in effect outside our faded render. */
    protected Composite _ocomp;

    /** The current alpha of the image. */
    protected float _alpha;

    /** The target alpha. */
    protected float _target;

    /** The alpha step per millisecond. */
    protected float _step;

    /** The starting alpha. */
    protected float _startAlpha;

    /** Time zero. */
    protected long _initStamp;
}

@@ -1236,80 +1236,380 @@
     
-// save things off%0A        _startAlpha = _alpha = Math.max(alpha, 0.0f);
+if ((step == 0f) %7C%7C (alpha %3E target && step %3E 0f) %7C%7C%0A                (alpha %3C target && step %3C 0f)) %7B%0A            throw new IllegalArgumentException(%22Step specified is illegal: %22 +%0A                %22Fade would never finish (start=%22 + alpha + %22, step=%22 + step +%0A                %22, target=%22 + target + %22)%22);%0A        %7D%0A%0A        // save things off%0A        _startAlpha = alpha; 
 %0A   
@@ -1649,30 +1649,14 @@
 t = 
-Math.min(target, 1.0f)
+target
 ;%0A%0A 
@@ -1694,16 +1694,74 @@
 mposite%0A
+        _alpha = Math.max(0f, Math.min(1f, _startAlpha));%0A
         
@@ -1872,32 +1872,59 @@
 ickStamp)%0A    %7B%0A
+        _finished = false;%0A
         _initSta
@@ -2002,87 +2002,17 @@
 urn 
-(_startAlpha %3C _target) ?%0A            (_alpha %3E= _target) : (_alpha %3C= _target)
+_finished
 ;%0A  
@@ -2262,24 +2262,155 @@
 s * _step);%0A
+        _finished = (_startAlpha %3C _target) ? (alpha %3E= _target)%0A                                            : (alpha %3C= _target);%0A
         if (
@@ -2698,32 +2698,35 @@
       %7D%0A%0A       
+ //
  return false;%0A 
@@ -2718,24 +2718,72 @@
 return false
+, unless we're finished%0A        return _finished
 ;%0A    %7D%0A%0A   
@@ -3517,11 +3517,82 @@
 itStamp;
+%0A%0A    /** True when we're finished. */%0A    protected boolean _finished;
 %0A%7D%0A

Allow the start or end alpha levels to be outside the normal range so that useful delays can be built into the beginning or end of the animation. Detect bogus parameters in the constructor and throw an exception to save developer head-scratching time when the animation doesn't actually do any fading.