[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Fenfire-dev] PEG animation_api--mudyc
From: |
Tuomas Lukka |
Subject: |
Re: [Fenfire-dev] PEG animation_api--mudyc |
Date: |
Fri, 24 Oct 2003 11:04:17 +0300 |
User-agent: |
Mutt/1.5.4i |
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