[Gzz-commits] libvob/doc/pegboard/vobscene_recursion--tjl peg...

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/libvob
Module name:    libvob
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/08/05 08:04:33

Modified files:
        doc/pegboard/vobscene_recursion--tjl: peg.rst 

Log message:
        Updating

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst.diff?tr1=1.5&tr2=1.6&r1=text&r2=text

Patches:
Index: libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst
diff -u libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst:1.5 
libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst:1.6
--- libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst:1.5     Wed May  7 
08:00:42 2003
+++ libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst Tue Aug  5 08:04:33 2003
@@ -3,8 +3,8 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/05/07 12:00:42 $
-:Revision: $Revision: 1.5 $
+:Last-Modified: $Date: 2003/08/05 12:04:33 $
+:Revision: $Revision: 1.6 $
 :Status:   Current
 
 Performance problems in PP show that we should soon make a big
@@ -22,6 +22,12 @@
     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*
+    the VobSceneVob. Therefore, it cannot be called a Vob.
+
+    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
@@ -32,12 +38,12 @@
     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) but
-    should be well worth it e.g. for PP.
+    should be well worth it e.g. for FenPDF.
 
 - How do we map between coordinate systems?
 
     RESOLVED: By explicitly creating a coordinate system in the parent
-    corresponding to a coordinate system in the child by a special method..
+    corresponding to a coordinate system in the child by a special method.
 
 - Modifications to child vobscenes?
 
@@ -45,7 +51,7 @@
     has been altered in any way **except** coordinate system parameter
     change gives undefined results for now. Possibly even crash.
 
-    This may change later.
+    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?
@@ -61,13 +67,20 @@
     later if necessary. This also makes matching, shouldBeRendered
     hierarchies &c inside the child easier to deal with for now.
 
-    Placing the child with a '-1' coordsys will, as a special convenience,
-    use the child's original coordinate system.
+    This requires creating the child with the knowledge of how 
+    the initial coordinate systems will be numbered -- an extra parameter
+    to createVobScene (reserveCS).
 
 - Should the child vobscene define the number of coordsys 
   in the beginning to replace with coordsys from the parent?
 
     RESOLVED: Yes. This makes it easier to use the Vob interface.
+    This is true for all VobScenes - the change of root vs unit below
+    raises the number from 1 to 2 for all vobscenes. This should be
+    a parameter.
+
+    We shall not define the default to be 2 but 2 or greater, for now -
+    we may want more than the 2 later on..
 
 - 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)?
@@ -82,59 +95,56 @@
     The unit box of CS 1 is set to screen size, while the unit box
     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. Such VobScenes cannot be used for normal
+    rendering without being inserted to a parent, though.
 
 - How do we get the coordinate systems into the child vobscene? 
 
-    RESOLVED: The child vobscene is placed as a normal Vob.
-    Normal Vobs will be extended on the Java level to what they
-    can do on the C++ level already: use arbitrary numbers of coordinate
-    systems.
+    RESOLVED: A special call in VobScene, since the child vobscene
+    needs a *key* from the parent coordinate system, to allow
+    interpolation..
 
 - Matching between different versions of a coordinate system?
 
-    RESOLVED: No, at least for now. The child VobScene is just a static
-    VobScene, rendered at the coordinates given by the parent. 
-    Nothing else.
+    RESOLVED: Yes, as described above.
 
 - Is a normal VobScene usable as a child vobscene? Or do we need special
   operations?
 
     RESOLVED: No. Too much overhead and difficulties. The correct way
-    is to create a VobSceneVob. There shall also be a call for creating
-    a coordinate system from one in the child vob.
+    is to create a VobScene by the 
+    ``GraphicsAPI.RenderingSurface.createChildVobScene(int reserveCS)``
+    call.  
 
 Changes
 =======
 
 The API changes are minor. 
 
-Allow N-parameter Vobs
-----------------------
+Creating Child VobScenes
+------------------------
 
-The current API only allows 0, 1, 2 and 3 -cs Vobs. This may not be
-enough with VobScene recursion.
+Extend ``GraphicsAPI.RenderingSurface`` by ::
 
-Add to VobPlacer (and all the classes mirroring it) the methods ::
-    
-    void put(Vob vob, int[] cs);
-    void put(Vob vob, int[] cs, int n);
-
-where ``n`` implies that the first n elements of the array should be used.
-
-VobSceneVob
------------
-
-A new Vob class which embeds a complete VobScene.
-
-    public class VobSceneVob implements Vob {
-       /** Create a new vobscenevob from the given VobScene.
-        * The given VobScene must not be modified after this call.
-        * @param scene The VobScene
-        * @param n The number of initial coordinate systems in scene
-        *      to replace with coordinate systems of the surrounding scene.
-        */
-       public VobSceneVob(VobScene scene, int n);
-    }
+    /** 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
+
+    /** Create a new vobscenevob from the given VobScene.
+     * The given VobScene must not be modified after this call.
+     * @param scene The VobScene
+     */
+     public void putChildVobScene(VobScene child, Object key, int[] cs);
 
 
 VobScene methods