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

[Matti Katila]

I abandon this peg because of count of unresolved issues and the 
misunderstanding of the idea between developers.


   -Matti





On Thu, 16 Oct 2003, Tuomas Lukka wrote:
> 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
>