Re: [Fenfire-dev] PEG animation_api--mudyc: Animation Layer API

[Tuomas Lukka]

On Wed, Oct 15, 2003 at 02:55:59PM +0300, Matti Katila wrote:
> On Wed, 15 Oct 2003, Tuomas Lukka wrote:
> > On Wed, Oct 15, 2003 at 01:08:29PM +0300, Matti Katila wrote:
> > > :Scope:    Minor
> > 
> > I think the scope is rather major...
> 
> No it's not and that's the point. I see this peg as qualify
> the org.fenfire.fenpdf.fenpdf.animation interface.

Sorry, you mean this is supposed to go into fenfire, not libvob?
Why?

Still, it *is* major - most code needs touching.

> This is not about timing for example:
> 
> -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.
> -
> -    All features in this peg are here because they are used in real 
> -    programs and them are well known already.
> 
> I think the 'resolved' answer says why it's not in the scope of this peg.

Why in the world did you REMOVE this issue from the PEG?

**DON'T REMOVE RESOLVED ISSUES FROM PEGS**

Otherwise, the same questions will get asked, again and again.

> > > 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 told the caller of ``chg``,
> > > for debugging::
> > > 
> > >     anim.animate("MouseEventHdl");
> > > 
> > > where ``anim`` is an instance of ``AnimationAPI``.
> > 
> > Issue: Is the string parameter needed? If you want debugging to show where
> > it was called, you can use a Throwable and print the stack trace
> > (without actually throwing an exception).
> 
> Does this work from both java and jython, e.g., something like PyObject is 
> not very informative?

It does. The Java stack trace has the Jython .py line numbers.

> > > 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.
> > 
> > I disagree. If it should never be called, there should not be a method.
> 
> This interface is application level, not framework(libvob) level.
> 
> If this interface would be framework level, all the methods would then 
> go to GraphicsAPI.Window or GraphicsAPI.RenderingSurface interface but 
> this is NOT framework level.

I still don't understand. Why should the framework not provide this?
API?

> > > ISSUE: If we don't want people to see AbstractUpdateManager
> > > should we hide some of it's methods to package private?
> > > 
> > >     Small demos might still need these methods.
> > >     Otoh, safer is better. One possibility is to 
> > >     add this API within the demo framework but then it would be
> > >     very hard to call from the java side.
> > 
> > So what is the resolution?
> 
> It's not resolved issue, so it is left open. 
> If I just resolve it by saing:
> 
> Resolved: No.
> 
> Then you would never accept this peg ;)

The PEG can't be accepted if there are any open issues anyway.
And you need to say *WHY* this is the resolution.

> At least I want to understand very deeply why would you like to hide the 
> method.

Ok.

When you define a new API for existing functionality, it's usually
appropriate to remove the old APIs if at all possible, to avoid
1) confusion
2) growing interface complexity
3) errors from using both levels of APIs.

> > I don't understand the last sentence at all.
> 
> Let's implement this interface in vob.putil.demo but then it would be hard 
> to call from Java.

Yes. I don't understand this at all.

It's an interface. Why is it hard to call from Java?

Why not make a Java object that's a helper for vob.putil.demo.

I know that you have a logical thought chain
leading to that, but you need to make it explicit. Please use more sentences ;)

> > I had raised some issues previously but I don't see them here. Where
> > did they go?
> 
> -ISSUE: Should the default be to animate or not to animate?
> -
> -    RESOLVED: chg() without update method set should throw an error.
> -    Explicity is better and it makes code cleaner somehow.
> 
> We (with benja) thought that it would be useles to have chg() so there's 
> no chg() in here.

Well, then you should keep the issue in PEG.

> > You should not delete issues, they are vital to keep in place so that
> > answers will be remembered, and especially the *REASONS* for those answers.
> 
> Try to take your position with these issues - sometimes they are fake and 
> now they are important even I have made changes what makes them no 
> more be in the scope of this peg.

My position is clear but I haven't made it clear enough.

Ok:

Issues are important when
someone has asked a question: Should we do X? 
Then, the question and the answer (the **CURRENT** answer) 
should be in the PEG.

If the PEG changes, the *RESOLUTION* of the issue may change,
and also the wording of the question may be changed to reflect
the changes so that it makes sense. 

ESPECIALLY important is that issues related to defining the *scope*
of a PEG are kept, like the animation thing. 

Also, the above "Should the default be to ..." -> change the RESOLUTION part.
To explain why this issue is moot, what the current idea is.


Then, *FAKE* issues are issues that are not actual points of contention or 
decision.
For example, "How is Foo currently handled?" is not an issue. It's something
that should be explained in the PEG section but it's not something that 
different
people would have different opinions about.

So, basically: 

        An ISSUE is something where there are several possible solutions
        and each one has reasonable arguments favoring them.

        An ISSUE is *NOT* any question about the subject matter.

        It's "Should we do X or should we do Y?", with the "Why?" implied.


> > > 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.**
> > > 
> > > For safety of event handling, possibility to check if 
> > > VobScene has changed is added into the animation layer.
> > 
> > I don't understand how that makes things safer. Please explain.
> 
> We have vobscene1
> 
> now mouse event1 happens to come in.
> 
> we say: change to next frame with animation.
> 
> (we now imagine that vobscene has changed)
> 
> mouse event2 comes in.
> 
> so, where's the red box which we expected to find from vobscene?
> or, where's the coordinate system which we expected to set parameters?
> 
> there's none because vobscene has not yet changed.
> so: 
> 
> if not anim.hasVSchanged(): return anim.animate('mouseEventHandler')
> 
> we'd not want to handle events which has no sense.

Ok, please explain this in the PEG.

> > > 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. 
> > 
> > If we'll remove AbstractUpdateManager.chg, then this is the *main* place
> > for it - you can't refer to other places. You have to explain here
> > how this will work..
> 
> I can't see the need for removing AbstractUpdateManager.chg() because
> this peg says only that animations are usually done with one way of 
> these three and by using this interface it defines them to be the three 
> ones.

Could you give an example of a different way? 

Something that's used somewhere?

You don't want the timing stuff in this API because you claim
it's not used but you don't want to remove something else
you haven't demonstrated is used?

ISSUE: I'd really love to not have people access UpdateManager directly
so if you want a low-level API as well, could we define another 
interface for that at the same time?

> > >      * <p>
> > >      * This interface sets strict policy for several routines.
> > >      *
> > >      *   1) 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.
> > 
> > >      *   2) 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.
> > 
> > ISSUE: Does there really need to exist a "lower-level animation interface"?
> >
> > >         /** Animate to next VobScene by creating a new VobScene.
> > >          */
> > >         void animate(String caller);
> > 
> > How does this routine know how to do that?
> 
> Is there many possibilities?
> 
> > Or does it actually *not* do what you say in the javadoc it does but
> > rather sets a flag or something?
> > 
> > See above about the issue on callers.

I mean: what would an implementation of this API actually do when that method
is called? Does it call someone to generate the new VobScene or what?

        Tuomas