/[libvob]/libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst
ViewVC logotype

Diff of /libvob/doc/pegboard/vobscene_recursion--tjl/peg.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.8 by tjl, Sun Sep 14 08:57:20 2003 UTC revision 1.9 by tjl, Sun Sep 14 11:59:39 2003 UTC
# Line 18  Issues Line 18  Issues
18  - Should we have a "VobSceneVob", i.e. a Vob that contains a different  - Should we have a "VobSceneVob", i.e. a Vob that contains a different
19    VobScene or some other approach?    VobScene or some other approach?
20    
21      RESOLVED: Something like that, but extended, since we want to export      RESOLVED: Too many special properties to be a Vob or a coordsys
22      several coordinate systems from the child vobscene to the parent,      directly.
     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)  
23    
24      In fact, it seems that we should support placing VobScenes directly.      We shall use a special ChildVobScene class.
25    
26  - What should the efficiency demands be? Linear w.r.t. child size?  - What should the efficiency demands be when including a child
27      and when rendering? Linear w.r.t. child size?
28    
29      RESOLVED: Linear is not good enough! Consider a huge canvas that      RESOLVED: Linear is not good enough! Consider a huge canvas that
30      has been generated and is placed into a viewport, and most of it is      has been generated and is placed into a viewport, and most of it is
31      culled away. One of the very reasons for this PEG is that we need      culled away. One of the very reasons for this PEG is that we need
32      to have more speed in this case.      to have more speed in this case.
33    
34      Therefore, the time should be linear w.r.t. the **rendered**      Therefore, the time to include a child should be **constant**,
35        and the time to render a vobscene should be **linear** w.r.t.
36        the *rendered*
37      coordsystems of the child, but constant w.r.t. child size. This makes      coordsystems of the child, but constant w.r.t. child size. This makes
38      life a bit more difficult internally (can't just copy a list, have      life a bit more difficult internally (can't just copy a list, have
39      to point to it) but should be well worth it e.g. for FenPDF.      to point to it) but should be well worth it e.g. for FenPDF.
# Line 55  Issues Line 51  Issues
51    
52      This may change later; easiest to start strict.      This may change later; easiest to start strict.
53    
54    - [benja] Should we throw an exception if a child vobscene is modified?
55    
56        RESOLVED: Too expensive - this is the innermost loops
57        of the Java code we are talking about, here.
58    
59  - Do we need to define coordinate systems other than the root of the  - Do we need to define coordinate systems other than the root of the
60    child from the parent?    child from the parent?
61    
# Line 106  Issues Line 107  Issues
107      needs a *key* from the parent coordinate system, to allow      needs a *key* from the parent coordinate system, to allow
108      interpolation (not implemented now).      interpolation (not implemented now).
109    
110  - Matching between different versions of a coordinate system?  - Matching between different versions of a child vobscene?
111    
112      RESOLVED: Later.      RESOLVED: Later.
113    
# Line 120  Issues Line 121  Issues
121      ``GraphicsAPI.RenderingSurface.createChildVobScene(int reserveCS)``      ``GraphicsAPI.RenderingSurface.createChildVobScene(int reserveCS)``
122      call.        call.  
123    
124    - [benja] Should child vobscenes be their own class?
125    
126        RESOLVED: Yes. Gives us type safety for placing child vobscenes.
127    
128    Introduction
129    ============
130    
131    This PEG proposes an important change to the VobScene model. So far,
132    the model has been (we'll ignore keys for a while):
133    
134        A VobScene contains coordinate systems, indexed by integers,
135        and a list of Vobs, each of which is associated with 0 or more coordsyses.
136    
137        The coordinate system 0 is the root (or unit) coordinate system, representing
138        screen coordinates.
139    
140    The new model is:
141    
142        A VobScene contains coordinate systems, indexed by integers,
143        and a list of Vobs, each of which is associated with 0 or more coordsyses.
144    
145        A VobScene can also contain a child VobScene, which is specially treated
146        both as a coordinate system *and* a Vob. A child VobScene can use a fixed
147        number of parameter coordinate systems from the parent. The VobScene can
148        also take coordinate systems from the child to use as normal coordinate
149        systems in the parent.
150    
151        The coordinate system 0 is the unit coordinate system in the root
152        vobscene and (by convention) others.
153    
154        The coordinate system 1 is the screen coordinate system, with the box size
155        giving the width/height in screen coordinates. This can also be used
156        as a convention in child vobscenes but is not as important as coordsys 0.
157    
158    This represents quite a complication; OTOH, the gains are important:
159    child VobScenes can be created directly as pure Functions of the structure,
160    allowing REALLY efficient caching &c.
161    
162  Changes  Changes
163  =======  =======
164    
165  The API changes are minor.  The API changes are minor.
166    
167    Child VobScene
168    --------------
169    
170    New class ``ChildVobScene``, extending ``VobScene``. No new methods.
171    
172  Creating Child VobScenes  Creating Child VobScenes
173  ------------------------  ------------------------
174    
# Line 132  Extend ``GraphicsAPI.RenderingSurface`` Line 176  Extend ``GraphicsAPI.RenderingSurface``
176    
177      /** Create a new VobScene that may be placed into a VobScene      /** Create a new VobScene that may be placed into a VobScene
178       * by the putChildVobScene call.       * by the putChildVobScene call.
179       * @param reserveCS The number of initial coordinate systems in scene       * @param numberOfParameterCS The number of initial coordinate systems in the child scene
180       *  to replace with coordinate systems of the surrounding scene.       *                  that are to be given to it as parameters from the parent.
181       */       */
182      VobScene createChildVobScene(Dimension size, int reserveCS);      ChildVobScene createChildVobScene(Dimension size, int numberOfParameterCS);
183    
184  Placing Child VobScenes  Placing Child VobScenes
185  -----------------------  -----------------------
186    
187  Extend ``VobScene`` by  Extend ``VobScene`` by::
188    
189      /** Place the given VobScene as a child.      /** Place the given VobScene as a child.
190       * The given VobScene must not be modified after this call.       * The given VobScene must not be modified after this call.
# Line 148  Extend ``VobScene`` by Line 192  Extend ``VobScene`` by
192       *          need to be created especially, through       *          need to be created especially, through
193       *          RenderingSurface.createChildVobScene       *          RenderingSurface.createChildVobScene
194       * @param key The key to use       * @param key The key to use
195         * @param cs The coordinate systems that shall be used as the first
196         *           coordinate systems of the child.
197         *           This *must* have the same number of elements as
198         *           the createChildVobScene method was given.
199       */       */
200       public void putChildVobScene(VobScene child, Object key, int[] cs);       public void putChildVobScene(ChildVobScene child, Object key, int[] cs);
201    
202  And correspondingly VobCoorder and VobPlacer by  And correspondingly VobCoorder by::
203    
204       public int _putChildVobScene(VobScene child, int[] cs)       public int _putChildVobScene(ChildVobScene child, int[] cs)
205    
206  (the VobScene method shall call both; the underscore means that  and VobPlacer by::
207  they should not be called by users).      
208         public int _putChildVobScene(ChildVobScene child, int coorderResult,
209                                            int[] cs)
210    
211  The key shall be passed to VobMatcher in the normal way.  (the VobScene method shall call both; the underscore means that
212    they should not be called by users. The VobScene method shall
213    return the result from VobPlacer).
214    
215  VobScene methods  The key shall be passed to VobMatcher in the normal way, using the integer
216  ----------------  returned by VobCoorder._putChildVobScene.
217    
218  Finally, a method getting VobSceneVob coordinate systems, in VobScene::  Exporting coordinate systems
219    ----------------------------
220    
221      public int subSceneCoordsys(int vobId, int nth);  Finally, a method exporting child coordinate systems into the
222    parent, in VobScene::
223    
224        /** Get a coordinate system from a child vobscene placed
225         * using putChildVobScene into this VobScene.
226         * @param childVobSceneId The id returned from putChildVobScene
227         * @param nth The index of the coordinate system
228         *            inside the child vobscene.
229         */
230        public int exportChildCoordsys(int childVobSceneId, int nth);
231    
232  VobScene semantics  VobScene semantics
233  ------------------  ------------------
234    
235  So far, the only special CS has been coordinate system 0.  So far, the only special CS has been coordinate system 0, which
236  From now on, coordinate system **1** shall be the "root" coordinate system,  has had the dual role of being both the "identity transformation"
237    and the "screen coordinate system".
238    
239    From now on, coordinate system **1** shall be the "screen" coordinate system,
240  and **0** remains the "identity" coordinate system (representing  and **0** remains the "identity" coordinate system (representing
241  an identity transformation).  an identity transformation).
242    
243  The unit box of CS 1 is set to screen size, while the unit box  The unit box of CS 1 is set to screen size, while the unit box
244  of CS 0 is (1,1).  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.  
   
   
   
   

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.9

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26