Re: [Fenfire-dev] PEG animation_api--mudyc

[Tuomas Lukka]

On Fri, Oct 24, 2003 at 10:22:20AM +0300, Matti Katila wrote:
> 
> ==========================================================================
> 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()

Typographical note: don't put "," and "or" into a list you typeset
with the fixed font.


> Current State
> =============

Since in the end of this section you start talking about what
this PEG does, I recommend "Introduction" here.

> We heavily use the ``demo framework`` in our applications, see
> vob.putil.demo. ``Demo framework`` basicly is libvob using one window.

Plus some convenience functions for reloading jython code
and switching between demo scenes.

> One window is obivious to get more testing with irregular edge.
> 
> Animation seen in window is made with one or two VobScenes.

This sentence needs some more articles ;)

> Although, VobScene is very sticky with *one* window we have no interfaces
> to handle them per *one* window.

I don't understand what you mean by "very sticky".

> 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.**

Which source tree? Libvob or fenfire?

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

Why? Why not a single general, fast, Java implementation?

> For safety of event handling, possibility to check if 
> VobScene has changed is added into the animation layer.

Changed since when? I still don't understand this.

> For example if we need to wait until something draws
> on screen, all events before that needs to be passed trough.

What?

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

I think you probably mean:

        Implementations of AnimationAPI should print out stack
        traces when debugging is enabled, to allow the programmer
        to see how the updates were initiated.

> Let's define the following interface: ::
> 
>     package org.nongnu.libvob.view;
>     import org.nongnu.libvob.VobScene;

ISSUE: What package should this interface be in?
libvob.view doesn't feel right - this isn't a view. How about
libvob proper?

>     /** 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. 

Better phrasing:
        The previously shown vobscene should not be stored anywhere else.


                        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>

Better phrasing:

        No other objects should call the low-level animation interface
        in AbstractUpdateManager.

>      */
>     public interface AnimationAPI {

ISSUE: Name for the interface. AnimationAPI is strange - there are
no other interfaces with "API" in them. 
WindowAnimation?

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

I'd like an example here. Who calls this, and what happens when?

>         /** 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:

"note", not "notice"

Is this supposed to *directly* rerender the current vobscene or
at the next suitable time? Is this defined or explicitly left undefined?

>          * 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 

"obivious"? "Currently visible"?

>          * 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.

This is a bit unclear.

Hmm... do you mean: whether the vobscene generation requested by
a previous animate or switchVS method is still pending?

Hmm, I'd prefer the other sense for this method:

        boolean previousVobsceneUnclean()

or something. That expresses it more clearly to me at least.

>          * <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();
>     } 
> 

        Tuomas