[Gzz-commits] libvob org/nongnu/libvob/VobScene.java test/vob...

[Matti Katila]

CVSROOT:        /cvsroot/libvob
Module name:    libvob
Changes by:     Matti Katila <address@hidden>   03/04/14 08:13:29

Modified files:
        org/nongnu/libvob: VobScene.java 
        test/vob/api   : vobcoorder.test 

Log message:
        add more docs to vobscene.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/org/nongnu/libvob/VobScene.java.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/test/vob/api/vobcoorder.test.diff?tr1=1.3&tr2=1.4&r1=text&r2=text

Patches:
Index: libvob/org/nongnu/libvob/VobScene.java
diff -u libvob/org/nongnu/libvob/VobScene.java:1.3 
libvob/org/nongnu/libvob/VobScene.java:1.4
--- libvob/org/nongnu/libvob/VobScene.java:1.3  Mon Mar 10 11:02:05 2003
+++ libvob/org/nongnu/libvob/VobScene.java      Mon Apr 14 08:13:29 2003
@@ -30,6 +30,20 @@
 
 /** A scene (keyframe) into which Vobs are placed.
  * <p>
+ * A VobScene encapsulates three separate systems: simple and orthogonal 
+ * coordinate systems, coordinate system mathing and coordinate systems 
+ * mapping to vobs. These systems are used to control the 
+ * main canvas called screen. VobScene can be used to make child coordinate 
+ * systems to this main canvas or to the coordinate system already made.
+ * So, all coordinate systems have parent coordinate system which is screen or 
+ * some other coordinate system created before. Once coordinate systems are 
+ * created and <i>matched</i> correctly there's no doubt to <i>map</i> a Vob 
+ * in the scene/screen/main canvas with <i>coordinate systems</i> given.
+ * <p>
+ * One important thing with one coordinate system is that they are 
+ * new coordinate systems which origin(0,0) is in up-left corner and 
point(1,1) is 
+ * in down-right corner.
+ * <p>
  * A VobScene is somewhat like a scene graph but has some rather special 
features.
  * Usually, VobScenes are <b>not</b> re-used between key presses: instead, the 
previous
  * scene (keyframe) is saved, a new one is generated, and an interpolation 
between
@@ -42,9 +56,10 @@
  * <p>
  * For example,
  * <pre>
-       // create a new coordinate system, at (100,100), with size (100,50).
+        // create a new coordinate system, at (100,100), scaled
+        // by 100 in x-direction and 50 in y-direction. 
        // In this coordinate system, the point (0,0) is mapped to (100,100) on 
screen
-       // and the point (1,1) is mapped to (200,50)
+       // and the point (1,1) is mapped to (200,50) because screen is the 0 
coordinate system. 
        int cs = vs.coords.ortho(0, 0, 100, 100, 100, 50);
        
        // set key of the coordinate system.
@@ -145,6 +160,13 @@
        this.size = size;
     }
 
+    /** Create an orthogonal coordinate system. For example
+     * <pre>
+            int cs = vs.coords.ortho(0, 0, 100, 100, 100, 50);
+     * </pre> 
+     * create a new coordinate system, at (100,100) in screen coordinates,
+     * scaled by 100 in x-direction and 50 in y-direction.
+     */
     final public int orthoCS(int into, Object key, float depth, 
                                float x, float y, float sx, float sy) {
        return matcher.add(into, coords.ortho(into,
@@ -157,10 +179,19 @@
                    float x, float y, float z) {
        return matcher.add(into, coords.translate(into, x, y, z), key);
     }
+    /** Create a scaled coordinate system. The point scale to is origin.
+     */
     public int scaleCS(int into, Object key, float sx, float sy) {
        return matcher.add(into, coords.scale(into, sx, sy), key);
     }
-    // Affine
+
+    /** Creates an affine coordinate system.
+     * AffineCS allows skewing and rotation, i.e. a general 2D affine 
+     * transformation and Z translation.
+     * <p>
+     * OrthoCS has the new x coordinate depend only on the old X coordinate,
+     * here it can depend both on the old X and Y coordinates.
+     */
     public int affineCS(int into, Object key,
            float depth, float cx, float cy,
            float x_x, float x_y, float y_x, float y_y) {
@@ -169,14 +200,26 @@
                        x_x, x_y, y_x, y_y), key
            );
     }
+
+    /** Create rotated coordinate system. Rotating point is origin.
+     */
     public int rotateCS(int into, Object key, float degrees) {
        return matcher.add(into, af().rotate(into, degrees), key);
     }
+
+    /** Create a scaled coordinate system. The point scale to is origin.
+     */
     public int scaleCS(int into, Object key, 
                            float sx, float sy, float sz) {
        return matcher.add(into, af().scale(into, sx, sy, sz), key);
     }
 
+    /** create a coordinate system such that its unit square
+     * goes orthogonally to the parent's box.
+     * I.e. if parent's box is (40,20)
+     * then (.5,.5) in the new coordsys maps to (20,10).
+     * It's basically a scale() which takes its parameters from the parent.
+     */
     public int unitSqCS(int into, Object key) {
        return matcher.add(into, coords.unitSq(into), key);
     }
@@ -229,8 +272,8 @@
     }
 
     /** Get the topmost activated coordsys at (x,y), whose nearest activated
-     *  * direct ancestor (not determining) is parent.
-     *   */
+     *  direct ancestor (not determining) is parent.
+     */
     public int getCSAt(int parent, float x, float y, float[] targetcoords) {
        return coords.getCSAt(parent, x, y, targetcoords);
     }
Index: libvob/test/vob/api/vobcoorder.test
diff -u libvob/test/vob/api/vobcoorder.test:1.3 
libvob/test/vob/api/vobcoorder.test:1.4
--- libvob/test/vob/api/vobcoorder.test:1.3     Fri Apr  4 14:26:47 2003
+++ libvob/test/vob/api/vobcoorder.test Mon Apr 14 08:13:29 2003
@@ -89,7 +89,7 @@
     vs.activate(cs1)
     
     cs2 = vs.translateCS(0, "trans_to_center", s.width/2, s.height/2)
-    cs3 = vs.orthoBoxCS(cs2, "box",0, -s.width/4, -s.height/4, 1,1, s.width/2, 
s.height/2)
+    cs3 = vs.orthoCS(cs2, "box",0, -s.width/4, -s.height/4, s.width/2, 
s.height/2)
     vs.activate(cs3)
 
     failUnlessEqual(cs3, c.getCSAt(0, s.width/2, s.height/2, None))