[Fenfire-dev] PEG animation_api--mudyc

[Matti Katila]

==========================================================================
PEG animation_api--mudyc: Animation Layer API 
==========================================================================

:Authors:  mudyc
:Date-Created: 2003-09-27
:Last-Modified: $Date: 2003/10/24 07:17:10 $
:Revision: $Revision: 1.11 $
:Status:   Current
:Stakeholders: mudyc, tjl, benja
:Scope:    Minor
:Type:     Policy, Interface


We have a very powerful system for drawing on the screen and animating.
In larger programs, where it's quite easy to create bugs,
the current API is misused more often. To make it easier to
debug the animation and events, I propose that we make a new layer for 
calling the animation routines.

Instead of calling::

    AbstractUpdateManager.chg()

directly, let us have a new API which is::

    anim.animate() ,
    anim.switchVS() or
    anim.rerenderVS()

where ``anim`` is an instance of ``AnimationAPI``.


Issues
======

ISSUE: How can we make sure that no other object calls the public method 
AbstractUpdateManager.chg()?

   RESOLVED: Use the source, Luke. Yes, we have source and we can 
   use the command ``grep`` to search trough source tree. After all, 
   this is easy to convert as a simple test.


ISSUE: If we don't want people to see AbstractUpdateManager
should we hide some of it's methods to package private?

    RESOLVED: Issue can be solved later because this PEG
    still gives a plenty of room for handling it in future. 
    Implementing the interfaace in demo framework also makes 
    it much more easier to use than old way and increments readability
    of source.


ISSUE: What about requesting a longer or shorter animation time,
or a non-standard animation curve (i.e. linear instead of the
vibrating exponential)?
Should this be covered by the animation API or bypassed to
AbstractUpdateManager? If there's a particular change that
should happen with a faster animation time (e.g. a menu closing)

    RESOLVED: Later. It's easy to add this feature into AnimationAPI:

        a) when we know issues with it,
        b) we have prototype of it and
        c) we have used the prototype in real program.
    
    This PEG is not about substitute of AbstractUpdateManager.
    This PEG is about handling one window and vobscenes close to it.


ISSUE: Should the default be to animate or not to animate?

    RESOLVED: Again, this is not about substitute of AbstractUpdateManager.
    Although, chg method should not called directly we explicitly call:
    'animation with time', '"animation" with very short time' or 'reuse
    VobScene'.


Current State
=============

We heavily use the ``demo framework`` in our applications, see
vob.putil.demo. ``Demo framework`` basicly is libvob using one window.
One window is obivious to get more testing with irregular edge.

Animation seen in window is made with one or two VobScenes.
Although, VobScene is very sticky with *one* window we have no interfaces
to handle them per *one* window.

This PEG tries to be a solution to provide an interface
for handling VobScenes per *one* window instead of
current UpdateManager which handles multiple windows and timing.

Currently we use AbstactUpdateManager directly from programs.
This is bad thing 'cause of it can prevent proper animation, e.g., 
by setting no animation even animation should be seen. 


Changes
=======

Create a new animation layer which encapsulates 
AbstractUpdateManager method calls, i.e, chg and setNoAnimation.
The new layer will be the only one that takes care of reusing VobScenes.
**No other objects are allowed to call the above named UpdateManager 
methods in the source tree, except small demos.**

AnimationAPI should be implemented in ``demo framework``.

For safety of event handling, possibility to check if 
VobScene has changed is added into the animation layer.
For example if we need to wait until something draws
on screen, all events before that needs to be passed trough.

Debugging of animation API should use java's stacktrace to 
print correct lines and classes.


Let's define the following interface: ::

    package org.nongnu.libvob.view;
    import org.nongnu.libvob.VobScene;

    /** An interface for providing common tool set for animation 
     * and animation debugging information.
     * This interface encapsulates the low-level animation interface
     * such as AbstractUpdateManagers' chg and setNoAnimation methods. 
     * <p>
     * This interface sets strict policy for several routines:
     * <OL><LI>
     *      There must not be other place to get previous/last 
     *      VobScene. If a VobScene is saved in other place than 
     *      here, it could prevent the GC to clean old VobScenes.
     *      By using only the correct 'previous' VobScene
     *      program can not get the famous 'invalid coorsys' bug.
     * </LI>
     * <LI>
     *      There must not be objects that call low-level animation 
     *      interface to change animation state. This could prevent
     *      proper animation, e.g., by setting no animation even when
     *      animation should be done.
     * </LI></OL>
     */
    public interface AnimationAPI {


        /** Animate to next VobScene by creating a new VobScene.
         */
        void animate();


        /** Switch to next VobScene by creating a new VobScene.
         * The switch is fast and no animation is seen.
         */
        void switchVS();


        /** Rerender the current VobScene. 
         * Changes in next frame are seen if coordinate system
         * parameters are set. Rerendering the current VobScene 
         * is much faster than creating a new VobScene, 
         * so e.g., any drag actions should be implemented to use
         * this method. 
         * <p>
         * Implementation notice:
         * Even though new coordinate systems can be created, the current 
         * coorder implementation uses finite range of coordinate systems. 
         * Creating too many new coordinate systems leads to
         * undefined behauviour.
         * @see VobCoorder
         */
        void rerender();
 

        /** Get the current visible vobscene. 
         * <p>
         * Prgogramming notice: When programming, you create vobscenes
         * for future usually, so this returns the obivious previous 
         * vobscene, e.g., to set coordinate system parameters.
         */
        VobScene getCurrentVS();


        /** Returns true if VobScene has changed from previous
         * <code>animate</code> or <code>switchVS</code> method.
         * <p>
         * Programming notice: 
         * In some situations when handling the events the programmer 
         * needs to know whether the VobScene is new or the still the old one,
         * e.g., when waiting the screen to update to move some new vob you
         * you need to pass all events trough before the screen has updated.
         */
        boolean hasVSchanged();
    }