[Fenfire-dev] PEG: Recursive vobscenes

[Tuomas Lukka]

This is the long-term solution to vobscene congestion.
Also should give a BIG speed boost to FenPDF and FenMM
and allow us to expand the functional approach a lot.

        Tuomas

=============================================================
PEG vobscene_recursion--tjl: 
=============================================================

:Author:   Tuomas J. Lukka
:Last-Modified: $Date: 2003/08/06 16:27:43 $
:Revision: $Revision: 1.7 $
:Status:   Current

Performance problems in FenPDF as well as running out 
of coordinate systems show that we should soon make a big
change I've been mulling over for some time: make vobscenes
hierarchical.

Issues
======

- Should we have a "VobSceneVob", i.e. a Vob that contains a different
  VobScene or some other approach?

    RESOLVED: Something like that, but extended, since we want to export
    several coordinate systems from the child vobscene to the parent,
    in order to do anchors. This cannot be done by a normal Vob so we need to
    really touch the VobScene itself.

    This is also because of interpolation: placing the "VobSceneVob"
    into the parent must have a key to allow interpolation *inside*
    a VobSceneVob. Therefore, it cannot be called a Vob. (This feature
    will be implemented only in the future)

    In fact, it seems that we should support placing VobScenes directly.

- What should the efficiency demands be? Linear w.r.t. child size?

    RESOLVED: Linear is not good enough! Consider a huge canvas that
    has been generated and is placed into a viewport, and most of it is
    culled away. One of the very reasons for this PEG is that we need
    to have more speed in this case.

    Therefore, the time should be linear w.r.t. the **rendered**
    coordsystems of the child, but constant w.r.t. child size. This makes
    life a bit more difficult internally (can't just copy a list, have
    to point to it) but should be well worth it e.g. for FenPDF.

- How do we map between coordinate systems of the parent and child vobscenes?

    RESOLVED: By a special method in the parent that returns a coordsys
    corresponding to a coordinate system in the child.

- Are modifications to child vobscenes allowed?

    RESOLVED: Using a vobscene after a child that was placed into it
    has been altered in any way **except** coordinate system parameter
    change gives undefined results for now. Possibly even crash.

    This may change later; easiest to start strict.

- Do we need to define coordinate systems other than the root of the
  child from the parent?

    RESOLVED: Yes. Even for the primitive use case outlined above,
    we need two: the canvas and the viewport coordinate systems.

- How generally do we need to define the coordinate systems 
  inside the child (the ones passed to the child as "parameters")?
  Alternatives: *n* from the beginning, or "random access" for
  redefining any coordinate systems of the child we like.

    RESOLVED: Initially, n from the beginning. We can generalize
    later if necessary. This also makes matching, shouldBeRendered
    hierarchies &c inside the child easier to deal with for now.

    This requires creating the child with the knowledge of how 
    the initial coordinate systems will be numbered -- an extra parameter
    to createVobScene (reserveCS).

    It is recommended that a class with constants is created to
    number the initial coordinate systems, for ease of access.

- What about coordinate system 0? Should it be special in the child
  and always correspond to cs 0 of the parent (i.e. unit transformation)?
  This is made problematic by the twim roles of coordinate system 0:
  on the one hand, it's the "root" coordinate system,
  on the other hand, it's the "no transofrmation" coordinate system.

    RESOLVED: It should not be special. 

    However, we should start a new convention: coordinate system **1**
    is the "root" coordinate system, and **0** remains the "identity"
    coordinate system.

    The box size of CS 1 is set to screen size, while the box size
    of CS 0 is (1,1)

    The semantics of 0 and 1 for child VobScenes are chosen 
    by the programmer, and the programmer can even specify 0 or 1 reserved
    coordinate systems. 

    It is **strongly** recommended that coordsyses 0 at the very least,
    and possibly 1 be used as per the convention for child coordinate
    systems as code may rely on those.

- How do we place the child vobscene and choose the vobscenes? 

    RESOLVED: A special call in VobScene, since the child vobscene
    needs a *key* from the parent coordinate system, to allow
    interpolation (not implemented now).

- Matching between different versions of a coordinate system?

    RESOLVED: Later.

- Is a normal VobScene usable as a child vobscene? Or do we need special
  operations?

    RESOLVED: No, it should not be usable. 
    Too much overhead and difficulties. 

    The correct way is to create a child VobScene by the 
    ``GraphicsAPI.RenderingSurface.createChildVobScene(int reserveCS)``
    call.  

Changes
=======

The API changes are minor. 

Creating Child VobScenes
------------------------

Extend ``GraphicsAPI.RenderingSurface`` by ::

    /** Create a new VobScene that may be placed into a VobScene
     * by the putChildVobScene call.
     * @param reserveCS The number of initial coordinate systems in scene
     *  to replace with coordinate systems of the surrounding scene.
     */
    VobScene createChildVobScene(Dimension size, int reserveCS);

Placing Child VobScenes
-----------------------

Extend ``VobScene`` by

    /** Place the given VobScene as a child.
     * The given VobScene must not be modified after this call.
     * @param child The child VobScene to place. Child vobscenes
     *          need to be created especially, through
     *          RenderingSurface.createChildVobScene
     * @param key The key to use
     */
     public void putChildVobScene(VobScene child, Object key, int[] cs);

And correspondingly VobCoorder and VobPlacer by

     public int _putChildVobScene(VobScene child, int[] cs)

(the VobScene method shall call both; the underscore means that 
they should not be called by users).

The key shall be passed to VobMatcher in the normal way.

VobScene methods 
----------------

Finally, a method getting VobSceneVob coordinate systems, in VobScene::

    public int subSceneCoordsys(int vobId, int nth);

VobScene semantics
------------------

So far, the only special CS has been coordinate system 0.
>From now on, coordinate system **1** shall be the "root" coordinate system,
and **0** remains the "identity" coordinate system (representing
an identity transformation).

The unit box of CS 1 is set to screen size, while the unit box
of CS 0 is (1,1).

OpenGL implementation
---------------------

In OpenGL, the recursion is implemented by a special coordinate system type
and a special Vob. 

The special coordinate system type causes the Coorder to call a method
to get the child coorder through an interface given to it, giving itself
as the parent parameter.