1 files changed, 148 insertions, 0 deletions

diff --git a/libraries/ode-0.9/contrib/GeomTransformGroup/README.txt b/libraries/ode-0.9/contrib/GeomTransformGroup/README.txt
new file mode 100644
index 0000000..bca0e66
--- /dev/null
+++ b/libraries/ode-0.9/contrib/GeomTransformGroup/README.txt
@@ -0,0 +1,148 @@
+README for GeomTransformGroup by Tim Schmidt.
+---------------------------------------------
+
+This is a patch to add the dGeomTransformGroup object to the list of geometry 
+objects.
+
+It should work with the cvs version of the ode library from 07/24/2002.
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+comment by russ smith: this code is easy to use with the rest of ODE.
+simply copy GeomTransformGroup.cpp to ode/src and copy GeomTransformGroup.h
+to include/ode. then add GeomTransformGroup.cpp to the ODE_SRC variable
+in the makefile. rebuild, and you're done! of course i could have done all
+this for you, but i prefer to keep GeomTransformGroup separated from the
+rest of ODE for now while other issues with the collision system are
+resolved.
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+Description:
+
+The dGeomTransformGroup is an adaption of the TransformGroup known from 
+Java3D (and maybe other libraries with a similar scene graph representation).
+It can be used to build an arbitrarily structured tree of objects that are 
+each positioned relative to the particular parent node.
+
+If you have a plane for example, there is one root node associated with the 
+plane's body and another three transformgroups placed 'under' this node. One 
+with the fuselage (cappedcylinder) under it and two with the underlying wings 
+(flat boxes). And if you want to add engines, simply put them 'next to' the 
+wings under another two transformgroups.
+
+bodyTG ---> associated with dBody
+    |
+    +--fuselageTG
+    |   |
+    |   +--fuselageCylinder
+    |
+    +--leftwingTG
+    |   |
+    |   +--wingBox
+    |   |
+    |   +--leftengineTG
+    |         |
+    |         +--leftengineCylinder
+    | 
+    +--rightwingTG
+        |
+        +--wingBox
+        |
+        +--rightengineTG
+              |
+              +--rightengineCylinder
+
+This is a method to easily compose objects without the necessity of always 
+calculating global coordinates. But apart from this there is something else 
+that makes dGeomTransformGroups very valuable.
+
+Maybe you remember that some users reported the problem of acquiring the 
+correct bodies to be attached by a contactjoint in the nearCallback when 
+using dGeomGroups and dGeomTransforms at the same time. This results from the 
+fact that dGeomGroups are not associated with bodies while all other 
+geometries are.
+
+So, as you can see in the nearCallback of the the test_buggy demo you have to 
+attach the contactjoint with the bodies that you get from the geometries that 
+are stored in the contact struct (-> dGeomGetBody(contacts[i].geom.g1)). 
+Normally you would do this by asking o1 and o2 directly with dGeomGetBody(o1) 
+and dGeomGetBody(o2) respectively.
+
+As a first approach you can overcome that problem by testing o1 and o2 if 
+they are groups or not to find out how to get the corresponding bodies.
+
+However this will fail if you want grouped transforms that are constructed 
+out of dGeomTransforms encapsulated in a dGeomGroup. According to the test 
+you use contacts[i].geom.g1 to get the right body. Unfortunately g1 is 
+encapsulated in a transform and therefore not attached to any body. In this 
+case the dGeomTransform 'in the middle' would have been the right object to 
+be asked for the body.
+
+You may now conclude that it is a good idea to unwrap the group encapsulated 
+geoms at the beginning of the nearcallback and use dGeomGetBody(o1) 
+consistently. But keep in mind that this also means not to invoke 
+dCollide(..) on groups at all and therefore not to expoit the capability of 
+dGeomGroups to speed up collision detection by the creation of bounding boxes 
+around the encapsulated geometry.
+
+Everything becomes even worse if you create a dGeomTransform that contains a 
+dGeomGroup of geoms. The function that cares about the collision of 
+transforms with other objects uses the position and rotation of the 
+respective encapsulated object to compute its final position and orientation. 
+Unfortunately dGeomGroups do not have a position and rotation, so the result 
+will not be what you have expected.
+
+Here the dGeomTransformGroups comes into operation, because it combines the 
+advantages and capabilities of the dGeomGroup and the dGeomTransform.
+And as an effect of synergy it is now even possible to set the position of a 
+group of geoms with one single command.
+Even nested encapsulations of dGeomTransformGroups in dGeomTransformGroups 
+should be possible (to be honest, I have not tried that so far ;-) ).
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+API:
+
+dGeomID dCreateGeomTransformGroup (dSpaceID space);
+  - create a GeomTransformGroup 
+    
+void dGeomTransformGroupAddGeom    (dGeomID tg, dGeomID obj);
+  - Comparable to dGeomTransformSetGeom or dGeomGroupAdd
+  - add objects to this group
+   
+void dGeomTransformGroupRemoveGeom (dGeomID tg, dGeomID obj);
+  - remove objects from this group
+
+void dGeomTransformGroupSetRelativePosition
+            (dGeomID g, dReal x, dReal y, dReal z);
+void dGeomTransformGroupSetRelativeRotation
+            (dGeomID g, const dMatrix3 R);
+  - Comparable to setting the position and rotation of all the
+    dGeomTransform encapsulated geometry. The difference 
+    is that it is global with respect to this group and therefore
+    affects all geoms in this group.
+  - The relative position and rotation are attributes of the 
+    transformgroup, so the position and rotation of the individual
+    geoms are not changed 
+
+const dReal * dGeomTransformGroupGetRelativePosition (dGeomID g);
+const dReal * dGeomTransformGroupGetRelativeRotation (dGeomID g);
+  - get the relative position and rotation
+  
+dGeomID dGeomTransformGroupGetGeom (dGeomID tg, int i);
+  - Comparable to dGeomGroupGetGeom
+  - get a specific geom of the group
+  
+int dGeomTransformGroupGetNumGeoms (dGeomID tg);
+  - Comparable to dGeomGroupGetNumGeoms
+  - get the number of geoms in the group
+  
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Tim Schmidt
+student of computer science
+University of Paderborn, Germany
+tisch@uni-paderborn.de