aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/ode-0.9/include/ode/objects.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/ode-0.9/include/ode/objects.h')
-rw-r--r--libraries/ode-0.9/include/ode/objects.h1966
1 files changed, 0 insertions, 1966 deletions
diff --git a/libraries/ode-0.9/include/ode/objects.h b/libraries/ode-0.9/include/ode/objects.h
deleted file mode 100644
index 3e24036..0000000
--- a/libraries/ode-0.9/include/ode/objects.h
+++ /dev/null
@@ -1,1966 +0,0 @@
1/*************************************************************************
2 * *
3 * Open Dynamics Engine, Copyright (C) 2001,2002 Russell L. Smith. *
4 * All rights reserved. Email: russ@q12.org Web: www.q12.org *
5 * *
6 * This library is free software; you can redistribute it and/or *
7 * modify it under the terms of EITHER: *
8 * (1) The GNU Lesser General Public License as published by the Free *
9 * Software Foundation; either version 2.1 of the License, or (at *
10 * your option) any later version. The text of the GNU Lesser *
11 * General Public License is included with this library in the *
12 * file LICENSE.TXT. *
13 * (2) The BSD-style license that is included with this library in *
14 * the file LICENSE-BSD.TXT. *
15 * *
16 * This library is distributed in the hope that it will be useful, *
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files *
19 * LICENSE.TXT and LICENSE-BSD.TXT for more details. *
20 * *
21 *************************************************************************/
22
23#ifndef _ODE_OBJECTS_H_
24#define _ODE_OBJECTS_H_
25
26#include <ode/common.h>
27#include <ode/mass.h>
28#include <ode/contact.h>
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/**
35 * @defgroup world World
36 *
37 * The world object is a container for rigid bodies and joints. Objects in
38 * different worlds can not interact, for example rigid bodies from two
39 * different worlds can not collide.
40 *
41 * All the objects in a world exist at the same point in time, thus one
42 * reason to use separate worlds is to simulate systems at different rates.
43 * Most applications will only need one world.
44 */
45
46
47/**
48 * @brief Create a new, empty world and return its ID number.
49 * @return an identifier
50 * @ingroup world
51 */
52ODE_API dWorldID dWorldCreate(void);
53
54
55/**
56 * @brief Destroy a world and everything in it.
57 *
58 * This includes all bodies, and all joints that are not part of a joint
59 * group. Joints that are part of a joint group will be deactivated, and
60 * can be destroyed by calling, for example, dJointGroupEmpty().
61 * @ingroup world
62 * @param world the identifier for the world the be destroyed.
63 */
64ODE_API void dWorldDestroy (dWorldID world);
65
66
67/**
68 * @brief Set the world's global gravity vector.
69 *
70 * The units are m/s^2, so Earth's gravity vector would be (0,0,-9.81),
71 * assuming that +z is up. The default is no gravity, i.e. (0,0,0).
72 *
73 * @ingroup world
74 */
75ODE_API void dWorldSetGravity (dWorldID, dReal x, dReal y, dReal z);
76
77
78/**
79 * @brief Get the gravity vector for a given world.
80 * @ingroup world
81 */
82ODE_API void dWorldGetGravity (dWorldID, dVector3 gravity);
83
84
85/**
86 * @brief Set the global ERP value, that controls how much error
87 * correction is performed in each time step.
88 * @ingroup world
89 * @param dWorldID the identifier of the world.
90 * @param erp Typical values are in the range 0.1--0.8. The default is 0.2.
91 */
92ODE_API void dWorldSetERP (dWorldID, dReal erp);
93
94/**
95 * @brief Get the error reduction parameter.
96 * @ingroup world
97 * @return ERP value
98 */
99ODE_API dReal dWorldGetERP (dWorldID);
100
101
102/**
103 * @brief Set the global CFM (constraint force mixing) value.
104 * @ingroup world
105 * @param cfm Typical values are in the range @m{10^{-9}} -- 1.
106 * The default is 10^-5 if single precision is being used, or 10^-10
107 * if double precision is being used.
108 */
109ODE_API void dWorldSetCFM (dWorldID, dReal cfm);
110
111/**
112 * @brief Get the constraint force mixing value.
113 * @ingroup world
114 * @return CFM value
115 */
116ODE_API dReal dWorldGetCFM (dWorldID);
117
118
119/**
120 * @brief Step the world.
121 *
122 * This uses a "big matrix" method that takes time on the order of m^3
123 * and memory on the order of m^2, where m is the total number of constraint
124 * rows. For large systems this will use a lot of memory and can be very slow,
125 * but this is currently the most accurate method.
126 * @ingroup world
127 * @param stepsize The number of seconds that the simulation has to advance.
128 */
129ODE_API void dWorldStep (dWorldID, dReal stepsize);
130
131
132/**
133 * @brief Converts an impulse to a force.
134 * @ingroup world
135 * @remarks
136 * If you want to apply a linear or angular impulse to a rigid body,
137 * instead of a force or a torque, then you can use this function to convert
138 * the desired impulse into a force/torque vector before calling the
139 * BodyAdd... function.
140 * The current algorithm simply scales the impulse by 1/stepsize,
141 * where stepsize is the step size for the next step that will be taken.
142 * This function is given a dWorldID because, in the future, the force
143 * computation may depend on integrator parameters that are set as
144 * properties of the world.
145 */
146ODE_API void dWorldImpulseToForce
147(
148 dWorldID, dReal stepsize,
149 dReal ix, dReal iy, dReal iz, dVector3 force
150);
151
152
153/**
154 * @brief Step the world.
155 * @ingroup world
156 * @remarks
157 * This uses an iterative method that takes time on the order of m*N
158 * and memory on the order of m, where m is the total number of constraint
159 * rows N is the number of iterations.
160 * For large systems this is a lot faster than dWorldStep(),
161 * but it is less accurate.
162 * @remarks
163 * QuickStep is great for stacks of objects especially when the
164 * auto-disable feature is used as well.
165 * However, it has poor accuracy for near-singular systems.
166 * Near-singular systems can occur when using high-friction contacts, motors,
167 * or certain articulated structures. For example, a robot with multiple legs
168 * sitting on the ground may be near-singular.
169 * @remarks
170 * There are ways to help overcome QuickStep's inaccuracy problems:
171 * \li Increase CFM.
172 * \li Reduce the number of contacts in your system (e.g. use the minimum
173 * number of contacts for the feet of a robot or creature).
174 * \li Don't use excessive friction in the contacts.
175 * \li Use contact slip if appropriate
176 * \li Avoid kinematic loops (however, kinematic loops are inevitable in
177 * legged creatures).
178 * \li Don't use excessive motor strength.
179 * \liUse force-based motors instead of velocity-based motors.
180 *
181 * Increasing the number of QuickStep iterations may help a little bit, but
182 * it is not going to help much if your system is really near singular.
183 */
184ODE_API void dWorldQuickStep (dWorldID w, dReal stepsize);
185
186
187/**
188 * @brief Set the number of iterations that the QuickStep method performs per
189 * step.
190 * @ingroup world
191 * @remarks
192 * More iterations will give a more accurate solution, but will take
193 * longer to compute.
194 * @param num The default is 20 iterations.
195 */
196ODE_API void dWorldSetQuickStepNumIterations (dWorldID, int num);
197
198
199/**
200 * @brief Get the number of iterations that the QuickStep method performs per
201 * step.
202 * @ingroup world
203 * @return nr of iterations
204 */
205ODE_API int dWorldGetQuickStepNumIterations (dWorldID);
206
207/**
208 * @brief Set the SOR over-relaxation parameter
209 * @ingroup world
210 * @param over_relaxation value to use by SOR
211 */
212ODE_API void dWorldSetQuickStepW (dWorldID, dReal over_relaxation);
213
214/**
215 * @brief Get the SOR over-relaxation parameter
216 * @ingroup world
217 * @returns the over-relaxation setting
218 */
219ODE_API dReal dWorldGetQuickStepW (dWorldID);
220
221/* World contact parameter functions */
222
223/**
224 * @brief Set the maximum correcting velocity that contacts are allowed
225 * to generate.
226 * @ingroup world
227 * @param vel The default value is infinity (i.e. no limit).
228 * @remarks
229 * Reducing this value can help prevent "popping" of deeply embedded objects.
230 */
231ODE_API void dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel);
232
233/**
234 * @brief Get the maximum correcting velocity that contacts are allowed
235 * to generated.
236 * @ingroup world
237 */
238ODE_API dReal dWorldGetContactMaxCorrectingVel (dWorldID);
239
240/**
241 * @brief Set the depth of the surface layer around all geometry objects.
242 * @ingroup world
243 * @remarks
244 * Contacts are allowed to sink into the surface layer up to the given
245 * depth before coming to rest.
246 * @param depth The default value is zero.
247 * @remarks
248 * Increasing this to some small value (e.g. 0.001) can help prevent
249 * jittering problems due to contacts being repeatedly made and broken.
250 */
251ODE_API void dWorldSetContactSurfaceLayer (dWorldID, dReal depth);
252
253/**
254 * @brief Get the depth of the surface layer around all geometry objects.
255 * @ingroup world
256 * @returns the depth
257 */
258ODE_API dReal dWorldGetContactSurfaceLayer (dWorldID);
259
260/* StepFast1 functions */
261
262/**
263 * @brief Step the world using the StepFast1 algorithm.
264 * @param stepsize the nr of seconds to advance the simulation.
265 * @param maxiterations The number of iterations to perform.
266 * @ingroup world
267 */
268ODE_API void dWorldStepFast1(dWorldID, dReal stepsize, int maxiterations);
269
270
271/**
272 * @defgroup disable Automatic Enabling and Disabling
273 *
274 * Every body can be enabled or disabled. Enabled bodies participate in the
275 * simulation, while disabled bodies are turned off and do not get updated
276 * during a simulation step. New bodies are always created in the enabled state.
277 *
278 * A disabled body that is connected through a joint to an enabled body will be
279 * automatically re-enabled at the next simulation step.
280 *
281 * Disabled bodies do not consume CPU time, therefore to speed up the simulation
282 * bodies should be disabled when they come to rest. This can be done automatically
283 * with the auto-disable feature.
284 *
285 * If a body has its auto-disable flag turned on, it will automatically disable
286 * itself when
287 * @li It has been idle for a given number of simulation steps.
288 * @li It has also been idle for a given amount of simulation time.
289 *
290 * A body is considered to be idle when the magnitudes of both its
291 * linear average velocity and angular average velocity are below given thresholds.
292 * The sample size for the average defaults to one and can be disabled by setting
293 * to zero with
294 *
295 * Thus, every body has six auto-disable parameters: an enabled flag, a idle step
296 * count, an idle time, linear/angular average velocity thresholds, and the
297 * average samples count.
298 *
299 * Newly created bodies get these parameters from world.
300 */
301
302/**
303 * @brief Set the AutoEnableDepth parameter used by the StepFast1 algorithm.
304 * @ingroup disable
305 */
306ODE_API void dWorldSetAutoEnableDepthSF1(dWorldID, int autoEnableDepth);
307
308/**
309 * @brief Get the AutoEnableDepth parameter used by the StepFast1 algorithm.
310 * @ingroup disable
311 */
312ODE_API int dWorldGetAutoEnableDepthSF1(dWorldID);
313
314/**
315 * @brief Get auto disable linear threshold for newly created bodies.
316 * @ingroup disable
317 * @return the threshold
318 */
319ODE_API dReal dWorldGetAutoDisableLinearThreshold (dWorldID);
320
321/**
322 * @brief Set auto disable linear threshold for newly created bodies.
323 * @param linear_threshold default is 0.01
324 * @ingroup disable
325 */
326ODE_API void dWorldSetAutoDisableLinearThreshold (dWorldID, dReal linear_threshold);
327
328/**
329 * @brief Get auto disable angular threshold for newly created bodies.
330 * @ingroup disable
331 * @return the threshold
332 */
333ODE_API dReal dWorldGetAutoDisableAngularThreshold (dWorldID);
334
335/**
336 * @brief Set auto disable angular threshold for newly created bodies.
337 * @param linear_threshold default is 0.01
338 * @ingroup disable
339 */
340ODE_API void dWorldSetAutoDisableAngularThreshold (dWorldID, dReal angular_threshold);
341
342/**
343 * @brief Get auto disable linear average threshold for newly created bodies.
344 * @ingroup disable
345 * @return the threshold
346 */
347ODE_API dReal dWorldGetAutoDisableLinearAverageThreshold (dWorldID);
348
349/**
350 * @brief Set auto disable linear average threshold for newly created bodies.
351 * @param linear_average_threshold default is 0.01
352 * @ingroup disable
353 */
354ODE_API void dWorldSetAutoDisableLinearAverageThreshold (dWorldID, dReal linear_average_threshold);
355
356/**
357 * @brief Get auto disable angular average threshold for newly created bodies.
358 * @ingroup disable
359 * @return the threshold
360 */
361ODE_API dReal dWorldGetAutoDisableAngularAverageThreshold (dWorldID);
362
363/**
364 * @brief Set auto disable angular average threshold for newly created bodies.
365 * @param linear_average_threshold default is 0.01
366 * @ingroup disable
367 */
368ODE_API void dWorldSetAutoDisableAngularAverageThreshold (dWorldID, dReal angular_average_threshold);
369
370/**
371 * @brief Get auto disable sample count for newly created bodies.
372 * @ingroup disable
373 * @return number of samples used
374 */
375ODE_API int dWorldGetAutoDisableAverageSamplesCount (dWorldID);
376
377/**
378 * @brief Set auto disable average sample count for newly created bodies.
379 * @ingroup disable
380 * @param average_samples_count Default is 1, meaning only instantaneous velocity is used.
381 * Set to zero to disable sampling and thus prevent any body from auto-disabling.
382 */
383ODE_API void dWorldSetAutoDisableAverageSamplesCount (dWorldID, unsigned int average_samples_count );
384
385/**
386 * @brief Get auto disable steps for newly created bodies.
387 * @ingroup disable
388 * @return nr of steps
389 */
390ODE_API int dWorldGetAutoDisableSteps (dWorldID);
391
392/**
393 * @brief Set auto disable steps for newly created bodies.
394 * @ingroup disable
395 * @param steps default is 10
396 */
397ODE_API void dWorldSetAutoDisableSteps (dWorldID, int steps);
398
399/**
400 * @brief Get auto disable time for newly created bodies.
401 * @ingroup disable
402 * @return nr of seconds
403 */
404ODE_API dReal dWorldGetAutoDisableTime (dWorldID);
405
406/**
407 * @brief Set auto disable time for newly created bodies.
408 * @ingroup disable
409 * @param time default is 0 seconds
410 */
411ODE_API void dWorldSetAutoDisableTime (dWorldID, dReal time);
412
413/**
414 * @brief Get auto disable flag for newly created bodies.
415 * @ingroup disable
416 * @return 0 or 1
417 */
418ODE_API int dWorldGetAutoDisableFlag (dWorldID);
419
420/**
421 * @brief Set auto disable flag for newly created bodies.
422 * @ingroup disable
423 * @param do_auto_disable default is false.
424 */
425ODE_API void dWorldSetAutoDisableFlag (dWorldID, int do_auto_disable);
426
427
428
429/**
430 * @defgroup bodies Rigid Bodies
431 *
432 * A rigid body has various properties from the point of view of the
433 * simulation. Some properties change over time:
434 *
435 * @li Position vector (x,y,z) of the body's point of reference.
436 * Currently the point of reference must correspond to the body's center of mass.
437 * @li Linear velocity of the point of reference, a vector (vx,vy,vz).
438 * @li Orientation of a body, represented by a quaternion (qs,qx,qy,qz) or
439 * a 3x3 rotation matrix.
440 * @li Angular velocity vector (wx,wy,wz) which describes how the orientation
441 * changes over time.
442 *
443 * Other body properties are usually constant over time:
444 *
445 * @li Mass of the body.
446 * @li Position of the center of mass with respect to the point of reference.
447 * In the current implementation the center of mass and the point of
448 * reference must coincide.
449 * @li Inertia matrix. This is a 3x3 matrix that describes how the body's mass
450 * is distributed around the center of mass. Conceptually each body has an
451 * x-y-z coordinate frame embedded in it that moves and rotates with the body.
452 *
453 * The origin of this coordinate frame is the body's point of reference. Some values
454 * in ODE (vectors, matrices etc) are relative to the body coordinate frame, and others
455 * are relative to the global coordinate frame.
456 *
457 * Note that the shape of a rigid body is not a dynamical property (except insofar as
458 * it influences the various mass properties). It is only collision detection that cares
459 * about the detailed shape of the body.
460 */
461
462
463/**
464 * @brief Get auto disable linear average threshold.
465 * @ingroup bodies
466 * @return the threshold
467 */
468ODE_API dReal dBodyGetAutoDisableLinearThreshold (dBodyID);
469
470/**
471 * @brief Set auto disable linear average threshold.
472 * @ingroup bodies
473 * @return the threshold
474 */
475ODE_API void dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_average_threshold);
476
477/**
478 * @brief Get auto disable angular average threshold.
479 * @ingroup bodies
480 * @return the threshold
481 */
482ODE_API dReal dBodyGetAutoDisableAngularThreshold (dBodyID);
483
484/**
485 * @brief Set auto disable angular average threshold.
486 * @ingroup bodies
487 * @return the threshold
488 */
489ODE_API void dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_average_threshold);
490
491/**
492 * @brief Get auto disable average size (samples count).
493 * @ingroup bodies
494 * @return the nr of steps/size.
495 */
496ODE_API int dBodyGetAutoDisableAverageSamplesCount (dBodyID);
497
498/**
499 * @brief Set auto disable average buffer size (average steps).
500 * @ingroup bodies
501 * @param average_samples_count the nr of samples to review.
502 */
503ODE_API void dBodySetAutoDisableAverageSamplesCount (dBodyID, unsigned int average_samples_count);
504
505
506/**
507 * @brief Get auto steps a body must be thought of as idle to disable
508 * @ingroup bodies
509 * @return the nr of steps
510 */
511ODE_API int dBodyGetAutoDisableSteps (dBodyID);
512
513/**
514 * @brief Set auto disable steps.
515 * @ingroup bodies
516 * @param steps the nr of steps.
517 */
518ODE_API void dBodySetAutoDisableSteps (dBodyID, int steps);
519
520/**
521 * @brief Get auto disable time.
522 * @ingroup bodies
523 * @return nr of seconds
524 */
525ODE_API dReal dBodyGetAutoDisableTime (dBodyID);
526
527/**
528 * @brief Set auto disable time.
529 * @ingroup bodies
530 * @param time nr of seconds.
531 */
532ODE_API void dBodySetAutoDisableTime (dBodyID, dReal time);
533
534/**
535 * @brief Get auto disable flag.
536 * @ingroup bodies
537 * @return 0 or 1
538 */
539ODE_API int dBodyGetAutoDisableFlag (dBodyID);
540
541/**
542 * @brief Set auto disable flag.
543 * @ingroup bodies
544 * @param do_auto_disable 0 or 1
545 */
546ODE_API void dBodySetAutoDisableFlag (dBodyID, int do_auto_disable);
547
548/**
549 * @brief Set auto disable defaults.
550 * @remarks
551 * Set the values for the body to those set as default for the world.
552 * @ingroup bodies
553 */
554ODE_API void dBodySetAutoDisableDefaults (dBodyID);
555
556
557/**
558 * @brief Retrives the world attached to te given body.
559 * @remarks
560 *
561 * @ingroup bodies
562 */
563ODE_API dWorldID dBodyGetWorld (dBodyID);
564
565/**
566 * @brief Create a body in given world.
567 * @remarks
568 * Default mass parameters are at position (0,0,0).
569 * @ingroup bodies
570 */
571ODE_API dBodyID dBodyCreate (dWorldID);
572
573/**
574 * @brief Destroy a body.
575 * @remarks
576 * All joints that are attached to this body will be put into limbo:
577 * i.e. unattached and not affecting the simulation, but they will NOT be
578 * deleted.
579 * @ingroup bodies
580 */
581ODE_API void dBodyDestroy (dBodyID);
582
583/**
584 * @brief Set the body's user-data pointer.
585 * @ingroup bodies
586 * @param data arbitraty pointer
587 */
588ODE_API void dBodySetData (dBodyID, void *data);
589
590/**
591 * @brief Get the body's user-data pointer.
592 * @ingroup bodies
593 * @return a pointer to the user's data.
594 */
595ODE_API void *dBodyGetData (dBodyID);
596
597/**
598 * @brief Set position of a body.
599 * @remarks
600 * After setting, the outcome of the simulation is undefined
601 * if the new configuration is inconsistent with the joints/constraints
602 * that are present.
603 * @ingroup bodies
604 */
605ODE_API void dBodySetPosition (dBodyID, dReal x, dReal y, dReal z);
606
607/**
608 * @brief Set the orientation of a body.
609 * @ingroup bodies
610 * @remarks
611 * After setting, the outcome of the simulation is undefined
612 * if the new configuration is inconsistent with the joints/constraints
613 * that are present.
614 */
615ODE_API void dBodySetRotation (dBodyID, const dMatrix3 R);
616
617/**
618 * @brief Set the orientation of a body.
619 * @ingroup bodies
620 * @remarks
621 * After setting, the outcome of the simulation is undefined
622 * if the new configuration is inconsistent with the joints/constraints
623 * that are present.
624 */
625ODE_API void dBodySetQuaternion (dBodyID, const dQuaternion q);
626
627/**
628 * @brief Set the linear velocity of a body.
629 * @ingroup bodies
630 */
631ODE_API void dBodySetLinearVel (dBodyID, dReal x, dReal y, dReal z);
632
633/**
634 * @brief Set the angular velocity of a body.
635 * @ingroup bodies
636 */
637ODE_API void dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z);
638
639/**
640 * @brief Get the position of a body.
641 * @ingroup bodies
642 * @remarks
643 * When getting, the returned values are pointers to internal data structures,
644 * so the vectors are valid until any changes are made to the rigid body
645 * system structure.
646 * @sa dBodyCopyPosition
647 */
648ODE_API const dReal * dBodyGetPosition (dBodyID);
649
650
651/**
652 * @brief Copy the position of a body into a vector.
653 * @ingroup bodies
654 * @param body the body to query
655 * @param pos a copy of the body position
656 * @sa dBodyGetPosition
657 */
658ODE_API void dBodyCopyPosition (dBodyID body, dVector3 pos);
659
660
661/**
662 * @brief Get the rotation of a body.
663 * @ingroup bodies
664 * @return pointer to a 4x3 rotation matrix.
665 */
666ODE_API const dReal * dBodyGetRotation (dBodyID);
667
668
669/**
670 * @brief Copy the rotation of a body.
671 * @ingroup bodies
672 * @param body the body to query
673 * @param R a copy of the rotation matrix
674 * @sa dBodyGetRotation
675 */
676ODE_API void dBodyCopyRotation (dBodyID, dMatrix3 R);
677
678
679/**
680 * @brief Get the rotation of a body.
681 * @ingroup bodies
682 * @return pointer to 4 scalars that represent the quaternion.
683 */
684ODE_API const dReal * dBodyGetQuaternion (dBodyID);
685
686
687/**
688 * @brief Copy the orientation of a body into a quaternion.
689 * @ingroup bodies
690 * @param body the body to query
691 * @param quat a copy of the orientation quaternion
692 * @sa dBodyGetQuaternion
693 */
694ODE_API void dBodyCopyQuaternion(dBodyID body, dQuaternion quat);
695
696
697/**
698 * @brief Get the linear velocity of a body.
699 * @ingroup bodies
700 */
701ODE_API const dReal * dBodyGetLinearVel (dBodyID);
702
703/**
704 * @brief Get the angular velocity of a body.
705 * @ingroup bodies
706 */
707ODE_API const dReal * dBodyGetAngularVel (dBodyID);
708
709/**
710 * @brief Set the mass of a body.
711 * @ingroup bodies
712 */
713ODE_API void dBodySetMass (dBodyID, const dMass *mass);
714
715/**
716 * @brief Get the mass of a body.
717 * @ingroup bodies
718 */
719ODE_API void dBodyGetMass (dBodyID, dMass *mass);
720
721/**
722 * @brief Add force at centre of mass of body in absolute coordinates.
723 * @ingroup bodies
724 */
725ODE_API void dBodyAddForce (dBodyID, dReal fx, dReal fy, dReal fz);
726
727/**
728 * @brief Add torque at centre of mass of body in absolute coordinates.
729 * @ingroup bodies
730 */
731ODE_API void dBodyAddTorque (dBodyID, dReal fx, dReal fy, dReal fz);
732
733/**
734 * @brief Add force at centre of mass of body in coordinates relative to body.
735 * @ingroup bodies
736 */
737ODE_API void dBodyAddRelForce (dBodyID, dReal fx, dReal fy, dReal fz);
738
739/**
740 * @brief Add torque at centre of mass of body in coordinates relative to body.
741 * @ingroup bodies
742 */
743ODE_API void dBodyAddRelTorque (dBodyID, dReal fx, dReal fy, dReal fz);
744
745/**
746 * @brief Add force at specified point in body in global coordinates.
747 * @ingroup bodies
748 */
749ODE_API void dBodyAddForceAtPos (dBodyID, dReal fx, dReal fy, dReal fz,
750 dReal px, dReal py, dReal pz);
751/**
752 * @brief Add force at specified point in body in local coordinates.
753 * @ingroup bodies
754 */
755ODE_API void dBodyAddForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz,
756 dReal px, dReal py, dReal pz);
757/**
758 * @brief Add force at specified point in body in global coordinates.
759 * @ingroup bodies
760 */
761ODE_API void dBodyAddRelForceAtPos (dBodyID, dReal fx, dReal fy, dReal fz,
762 dReal px, dReal py, dReal pz);
763/**
764 * @brief Add force at specified point in body in local coordinates.
765 * @ingroup bodies
766 */
767ODE_API void dBodyAddRelForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz,
768 dReal px, dReal py, dReal pz);
769
770/**
771 * @brief Return the current accumulated force vector.
772 * @return points to an array of 3 reals.
773 * @remarks
774 * The returned values are pointers to internal data structures, so
775 * the vectors are only valid until any changes are made to the rigid
776 * body system.
777 * @ingroup bodies
778 */
779ODE_API const dReal * dBodyGetForce (dBodyID);
780
781/**
782 * @brief Return the current accumulated torque vector.
783 * @return points to an array of 3 reals.
784 * @remarks
785 * The returned values are pointers to internal data structures, so
786 * the vectors are only valid until any changes are made to the rigid
787 * body system.
788 * @ingroup bodies
789 */
790ODE_API const dReal * dBodyGetTorque (dBodyID);
791
792/**
793 * @brief Set the body force accumulation vector.
794 * @remarks
795 * This is mostly useful to zero the force and torque for deactivated bodies
796 * before they are reactivated, in the case where the force-adding functions
797 * were called on them while they were deactivated.
798 * @ingroup bodies
799 */
800ODE_API void dBodySetForce (dBodyID b, dReal x, dReal y, dReal z);
801
802/**
803 * @brief Set the body torque accumulation vector.
804 * @remarks
805 * This is mostly useful to zero the force and torque for deactivated bodies
806 * before they are reactivated, in the case where the force-adding functions
807 * were called on them while they were deactivated.
808 * @ingroup bodies
809 */
810ODE_API void dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z);
811
812/**
813 * @brief Get world position of a relative point on body.
814 * @ingroup bodies
815 * @param result will contain the result.
816 */
817ODE_API void dBodyGetRelPointPos
818(
819 dBodyID, dReal px, dReal py, dReal pz,
820 dVector3 result
821);
822
823/**
824 * @brief Get velocity vector in global coords of a relative point on body.
825 * @ingroup bodies
826 * @param result will contain the result.
827 */
828ODE_API void dBodyGetRelPointVel
829(
830 dBodyID, dReal px, dReal py, dReal pz,
831 dVector3 result
832);
833
834/**
835 * @brief Get velocity vector in global coords of a globally
836 * specified point on a body.
837 * @ingroup bodies
838 * @param result will contain the result.
839 */
840ODE_API void dBodyGetPointVel
841(
842 dBodyID, dReal px, dReal py, dReal pz,
843 dVector3 result
844);
845
846/**
847 * @brief takes a point in global coordinates and returns
848 * the point's position in body-relative coordinates.
849 * @remarks
850 * This is the inverse of dBodyGetRelPointPos()
851 * @ingroup bodies
852 * @param result will contain the result.
853 */
854ODE_API void dBodyGetPosRelPoint
855(
856 dBodyID, dReal px, dReal py, dReal pz,
857 dVector3 result
858);
859
860/**
861 * @brief Convert from local to world coordinates.
862 * @ingroup bodies
863 * @param result will contain the result.
864 */
865ODE_API void dBodyVectorToWorld
866(
867 dBodyID, dReal px, dReal py, dReal pz,
868 dVector3 result
869);
870
871/**
872 * @brief Convert from world to local coordinates.
873 * @ingroup bodies
874 * @param result will contain the result.
875 */
876ODE_API void dBodyVectorFromWorld
877(
878 dBodyID, dReal px, dReal py, dReal pz,
879 dVector3 result
880);
881
882/**
883 * @brief controls the way a body's orientation is updated at each timestep.
884 * @ingroup bodies
885 * @param mode can be 0 or 1:
886 * \li 0: An ``infinitesimal'' orientation update is used.
887 * This is fast to compute, but it can occasionally cause inaccuracies
888 * for bodies that are rotating at high speed, especially when those
889 * bodies are joined to other bodies.
890 * This is the default for every new body that is created.
891 * \li 1: A ``finite'' orientation update is used.
892 * This is more costly to compute, but will be more accurate for high
893 * speed rotations.
894 * @remarks
895 * Note however that high speed rotations can result in many types of
896 * error in a simulation, and the finite mode will only fix one of those
897 * sources of error.
898 */
899ODE_API void dBodySetFiniteRotationMode (dBodyID, int mode);
900
901/**
902 * @brief sets the finite rotation axis for a body.
903 * @ingroup bodies
904 * @remarks
905 * This is axis only has meaning when the finite rotation mode is set
906 * If this axis is zero (0,0,0), full finite rotations are performed on
907 * the body.
908 * If this axis is nonzero, the body is rotated by performing a partial finite
909 * rotation along the axis direction followed by an infinitesimal rotation
910 * along an orthogonal direction.
911 * @remarks
912 * This can be useful to alleviate certain sources of error caused by quickly
913 * spinning bodies. For example, if a car wheel is rotating at high speed
914 * you can call this function with the wheel's hinge axis as the argument to
915 * try and improve its behavior.
916 */
917ODE_API void dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z);
918
919/**
920 * @brief Get the way a body's orientation is updated each timestep.
921 * @ingroup bodies
922 * @return the mode 0 (infitesimal) or 1 (finite).
923 */
924ODE_API int dBodyGetFiniteRotationMode (dBodyID);
925
926/**
927 * @brief Get the finite rotation axis.
928 * @param result will contain the axis.
929 * @ingroup bodies
930 */
931ODE_API void dBodyGetFiniteRotationAxis (dBodyID, dVector3 result);
932
933/**
934 * @brief Get the number of joints that are attached to this body.
935 * @ingroup bodies
936 * @return nr of joints
937 */
938ODE_API int dBodyGetNumJoints (dBodyID b);
939
940/**
941 * @brief Return a joint attached to this body, given by index.
942 * @ingroup bodies
943 * @param index valid range is 0 to n-1 where n is the value returned by
944 * dBodyGetNumJoints().
945 */
946ODE_API dJointID dBodyGetJoint (dBodyID, int index);
947
948/**
949 * @brief Manually enable a body.
950 * @param dBodyID identification of body.
951 * @ingroup bodies
952 */
953ODE_API void dBodyEnable (dBodyID);
954
955/**
956 * @brief Manually disable a body.
957 * @ingroup bodies
958 * @remarks
959 * A disabled body that is connected through a joint to an enabled body will
960 * be automatically re-enabled at the next simulation step.
961 */
962ODE_API void dBodyDisable (dBodyID);
963
964/**
965 * @brief Check wether a body is enabled.
966 * @ingroup bodies
967 * @return 1 if a body is currently enabled or 0 if it is disabled.
968 */
969ODE_API int dBodyIsEnabled (dBodyID);
970
971/**
972 * @brief Set whether the body is influenced by the world's gravity or not.
973 * @ingroup bodies
974 * @param mode when nonzero gravity affects this body.
975 * @remarks
976 * Newly created bodies are always influenced by the world's gravity.
977 */
978ODE_API void dBodySetGravityMode (dBodyID b, int mode);
979
980/**
981 * @brief Get whether the body is influenced by the world's gravity or not.
982 * @ingroup bodies
983 * @return nonzero means gravity affects this body.
984 */
985ODE_API int dBodyGetGravityMode (dBodyID b);
986
987
988
989/**
990 * @defgroup joints Joints
991 *
992 * In real life a joint is something like a hinge, that is used to connect two
993 * objects.
994 * In ODE a joint is very similar: It is a relationship that is enforced between
995 * two bodies so that they can only have certain positions and orientations
996 * relative to each other.
997 * This relationship is called a constraint -- the words joint and
998 * constraint are often used interchangeably.
999 *
1000 * A joint has a set of parameters that can be set. These include:
1001 *
1002 *
1003 * \li dParamLoStop Low stop angle or position. Setting this to
1004 * -dInfinity (the default value) turns off the low stop.
1005 * For rotational joints, this stop must be greater than -pi to be
1006 * effective.
1007 * \li dParamHiStop High stop angle or position. Setting this to
1008 * dInfinity (the default value) turns off the high stop.
1009 * For rotational joints, this stop must be less than pi to be
1010 * effective.
1011 * If the high stop is less than the low stop then both stops will
1012 * be ineffective.
1013 * \li dParamVel Desired motor velocity (this will be an angular or
1014 * linear velocity).
1015 * \li dParamFMax The maximum force or torque that the motor will use to
1016 * achieve the desired velocity.
1017 * This must always be greater than or equal to zero.
1018 * Setting this to zero (the default value) turns off the motor.
1019 * \li dParamFudgeFactor The current joint stop/motor implementation has
1020 * a small problem:
1021 * when the joint is at one stop and the motor is set to move it away
1022 * from the stop, too much force may be applied for one time step,
1023 * causing a ``jumping'' motion.
1024 * This fudge factor is used to scale this excess force.
1025 * It should have a value between zero and one (the default value).
1026 * If the jumping motion is too visible in a joint, the value can be
1027 * reduced.
1028 * Making this value too small can prevent the motor from being able to
1029 * move the joint away from a stop.
1030 * \li dParamBounce The bouncyness of the stops.
1031 * This is a restitution parameter in the range 0..1.
1032 * 0 means the stops are not bouncy at all, 1 means maximum bouncyness.
1033 * \li dParamCFM The constraint force mixing (CFM) value used when not
1034 * at a stop.
1035 * \li dParamStopERP The error reduction parameter (ERP) used by the
1036 * stops.
1037 * \li dParamStopCFM The constraint force mixing (CFM) value used by the
1038 * stops. Together with the ERP value this can be used to get spongy or
1039 * soft stops.
1040 * Note that this is intended for unpowered joints, it does not really
1041 * work as expected when a powered joint reaches its limit.
1042 * \li dParamSuspensionERP Suspension error reduction parameter (ERP).
1043 * Currently this is only implemented on the hinge-2 joint.
1044 * \li dParamSuspensionCFM Suspension constraint force mixing (CFM) value.
1045 * Currently this is only implemented on the hinge-2 joint.
1046 *
1047 * If a particular parameter is not implemented by a given joint, setting it
1048 * will have no effect.
1049 * These parameter names can be optionally followed by a digit (2 or 3)
1050 * to indicate the second or third set of parameters, e.g. for the second axis
1051 * in a hinge-2 joint, or the third axis in an AMotor joint.
1052 */
1053
1054
1055/**
1056 * @brief Create a new joint of the ball type.
1057 * @ingroup joints
1058 * @remarks
1059 * The joint is initially in "limbo" (i.e. it has no effect on the simulation)
1060 * because it does not connect to any bodies.
1061 * @param dJointGroupID set to 0 to allocate the joint normally.
1062 * If it is nonzero the joint is allocated in the given joint group.
1063 */
1064ODE_API dJointID dJointCreateBall (dWorldID, dJointGroupID);
1065
1066/**
1067 * @brief Create a new joint of the hinge type.
1068 * @ingroup joints
1069 * @param dJointGroupID set to 0 to allocate the joint normally.
1070 * If it is nonzero the joint is allocated in the given joint group.
1071 */
1072ODE_API dJointID dJointCreateHinge (dWorldID, dJointGroupID);
1073
1074/**
1075 * @brief Create a new joint of the slider type.
1076 * @ingroup joints
1077 * @param dJointGroupID set to 0 to allocate the joint normally.
1078 * If it is nonzero the joint is allocated in the given joint group.
1079 */
1080ODE_API dJointID dJointCreateSlider (dWorldID, dJointGroupID);
1081
1082/**
1083 * @brief Create a new joint of the contact type.
1084 * @ingroup joints
1085 * @param dJointGroupID set to 0 to allocate the joint normally.
1086 * If it is nonzero the joint is allocated in the given joint group.
1087 */
1088ODE_API dJointID dJointCreateContact (dWorldID, dJointGroupID, const dContact *);
1089
1090/**
1091 * @brief Create a new joint of the hinge2 type.
1092 * @ingroup joints
1093 * @param dJointGroupID set to 0 to allocate the joint normally.
1094 * If it is nonzero the joint is allocated in the given joint group.
1095 */
1096ODE_API dJointID dJointCreateHinge2 (dWorldID, dJointGroupID);
1097
1098/**
1099 * @brief Create a new joint of the universal type.
1100 * @ingroup joints
1101 * @param dJointGroupID set to 0 to allocate the joint normally.
1102 * If it is nonzero the joint is allocated in the given joint group.
1103 */
1104ODE_API dJointID dJointCreateUniversal (dWorldID, dJointGroupID);
1105
1106/**
1107 * @brief Create a new joint of the PR (Prismatic and Rotoide) type.
1108 * @ingroup joints
1109 * @param dJointGroupID set to 0 to allocate the joint normally.
1110 * If it is nonzero the joint is allocated in the given joint group.
1111 */
1112ODE_API dJointID dJointCreatePR (dWorldID, dJointGroupID);
1113
1114/**
1115 * @brief Create a new joint of the fixed type.
1116 * @ingroup joints
1117 * @param dJointGroupID set to 0 to allocate the joint normally.
1118 * If it is nonzero the joint is allocated in the given joint group.
1119 */
1120ODE_API dJointID dJointCreateFixed (dWorldID, dJointGroupID);
1121
1122ODE_API dJointID dJointCreateNull (dWorldID, dJointGroupID);
1123
1124/**
1125 * @brief Create a new joint of the A-motor type.
1126 * @ingroup joints
1127 * @param dJointGroupID set to 0 to allocate the joint normally.
1128 * If it is nonzero the joint is allocated in the given joint group.
1129 */
1130ODE_API dJointID dJointCreateAMotor (dWorldID, dJointGroupID);
1131
1132/**
1133 * @brief Create a new joint of the L-motor type.
1134 * @ingroup joints
1135 * @param dJointGroupID set to 0 to allocate the joint normally.
1136 * If it is nonzero the joint is allocated in the given joint group.
1137 */
1138ODE_API dJointID dJointCreateLMotor (dWorldID, dJointGroupID);
1139
1140/**
1141 * @brief Create a new joint of the plane-2d type.
1142 * @ingroup joints
1143 * @param dJointGroupID set to 0 to allocate the joint normally.
1144 * If it is nonzero the joint is allocated in the given joint group.
1145 */
1146ODE_API dJointID dJointCreatePlane2D (dWorldID, dJointGroupID);
1147
1148/**
1149 * @brief Destroy a joint.
1150 * @ingroup joints
1151 *
1152 * disconnects it from its attached bodies and removing it from the world.
1153 * However, if the joint is a member of a group then this function has no
1154 * effect - to destroy that joint the group must be emptied or destroyed.
1155 */
1156ODE_API void dJointDestroy (dJointID);
1157
1158
1159/**
1160 * @brief Create a joint group
1161 * @ingroup joints
1162 * @param max_size deprecated. Set to 0.
1163 */
1164ODE_API dJointGroupID dJointGroupCreate (int max_size);
1165
1166/**
1167 * @brief Destroy a joint group.
1168 * @ingroup joints
1169 *
1170 * All joints in the joint group will be destroyed.
1171 */
1172ODE_API void dJointGroupDestroy (dJointGroupID);
1173
1174/**
1175 * @brief Empty a joint group.
1176 * @ingroup joints
1177 *
1178 * All joints in the joint group will be destroyed,
1179 * but the joint group itself will not be destroyed.
1180 */
1181ODE_API void dJointGroupEmpty (dJointGroupID);
1182
1183/**
1184 * @brief Attach the joint to some new bodies.
1185 * @ingroup joints
1186 *
1187 * If the joint is already attached, it will be detached from the old bodies
1188 * first.
1189 * To attach this joint to only one body, set body1 or body2 to zero - a zero
1190 * body refers to the static environment.
1191 * Setting both bodies to zero puts the joint into "limbo", i.e. it will
1192 * have no effect on the simulation.
1193 * @remarks
1194 * Some joints, like hinge-2 need to be attached to two bodies to work.
1195 */
1196ODE_API void dJointAttach (dJointID, dBodyID body1, dBodyID body2);
1197
1198/**
1199 * @brief Set the user-data pointer
1200 * @ingroup joints
1201 */
1202ODE_API void dJointSetData (dJointID, void *data);
1203
1204/**
1205 * @brief Get the user-data pointer
1206 * @ingroup joints
1207 */
1208ODE_API void *dJointGetData (dJointID);
1209
1210/**
1211 * @brief Get the type of the joint
1212 * @ingroup joints
1213 * @return the type, being one of these:
1214 * \li JointTypeBall
1215 * \li JointTypeHinge
1216 * \li JointTypeSlider
1217 * \li JointTypeContact
1218 * \li JointTypeUniversal
1219 * \li JointTypeHinge2
1220 * \li JointTypeFixed
1221 * \li JointTypeAMotor
1222 * \li JointTypeLMotor
1223 */
1224ODE_API int dJointGetType (dJointID);
1225
1226/**
1227 * @brief Return the bodies that this joint connects.
1228 * @ingroup joints
1229 * @param index return the first (0) or second (1) body.
1230 * @remarks
1231 * If one of these returned body IDs is zero, the joint connects the other body
1232 * to the static environment.
1233 * If both body IDs are zero, the joint is in ``limbo'' and has no effect on
1234 * the simulation.
1235 */
1236ODE_API dBodyID dJointGetBody (dJointID, int index);
1237
1238/**
1239 * @brief Sets the datastructure that is to receive the feedback.
1240 *
1241 * The feedback can be used by the user, so that it is known how
1242 * much force an individual joint exerts.
1243 * @ingroup joints
1244 */
1245ODE_API void dJointSetFeedback (dJointID, dJointFeedback *);
1246
1247/**
1248 * @brief Gets the datastructure that is to receive the feedback.
1249 * @ingroup joints
1250 */
1251ODE_API dJointFeedback *dJointGetFeedback (dJointID);
1252
1253/**
1254 * @brief Set the joint anchor point.
1255 * @ingroup joints
1256 *
1257 * The joint will try to keep this point on each body
1258 * together. The input is specified in world coordinates.
1259 */
1260ODE_API void dJointSetBallAnchor (dJointID, dReal x, dReal y, dReal z);
1261
1262/**
1263 * @brief Set the joint anchor point.
1264 * @ingroup joints
1265 */
1266ODE_API void dJointSetBallAnchor2 (dJointID, dReal x, dReal y, dReal z);
1267
1268/**
1269 * @brief Param setting for Ball joints
1270 * @ingroup joints
1271 */
1272ODE_API void dJointSetBallParam (dJointID, int parameter, dReal value);
1273
1274/**
1275 * @brief Set hinge anchor parameter.
1276 * @ingroup joints
1277 */
1278ODE_API void dJointSetHingeAnchor (dJointID, dReal x, dReal y, dReal z);
1279
1280ODE_API void dJointSetHingeAnchorDelta (dJointID, dReal x, dReal y, dReal z, dReal ax, dReal ay, dReal az);
1281
1282/**
1283 * @brief Set hinge axis.
1284 * @ingroup joints
1285 */
1286ODE_API void dJointSetHingeAxis (dJointID, dReal x, dReal y, dReal z);
1287
1288/**
1289 * @brief set joint parameter
1290 * @ingroup joints
1291 */
1292ODE_API void dJointSetHingeParam (dJointID, int parameter, dReal value);
1293
1294/**
1295 * @brief Applies the torque about the hinge axis.
1296 *
1297 * That is, it applies a torque with specified magnitude in the direction
1298 * of the hinge axis, to body 1, and with the same magnitude but in opposite
1299 * direction to body 2. This function is just a wrapper for dBodyAddTorque()}
1300 * @ingroup joints
1301 */
1302ODE_API void dJointAddHingeTorque(dJointID joint, dReal torque);
1303
1304/**
1305 * @brief set the joint axis
1306 * @ingroup joints
1307 */
1308ODE_API void dJointSetSliderAxis (dJointID, dReal x, dReal y, dReal z);
1309
1310/**
1311 * @ingroup joints
1312 */
1313ODE_API void dJointSetSliderAxisDelta (dJointID, dReal x, dReal y, dReal z, dReal ax, dReal ay, dReal az);
1314
1315/**
1316 * @brief set joint parameter
1317 * @ingroup joints
1318 */
1319ODE_API void dJointSetSliderParam (dJointID, int parameter, dReal value);
1320
1321/**
1322 * @brief Applies the given force in the slider's direction.
1323 *
1324 * That is, it applies a force with specified magnitude, in the direction of
1325 * slider's axis, to body1, and with the same magnitude but opposite
1326 * direction to body2. This function is just a wrapper for dBodyAddForce().
1327 * @ingroup joints
1328 */
1329ODE_API void dJointAddSliderForce(dJointID joint, dReal force);
1330
1331/**
1332 * @brief set anchor
1333 * @ingroup joints
1334 */
1335ODE_API void dJointSetHinge2Anchor (dJointID, dReal x, dReal y, dReal z);
1336
1337/**
1338 * @brief set axis
1339 * @ingroup joints
1340 */
1341ODE_API void dJointSetHinge2Axis1 (dJointID, dReal x, dReal y, dReal z);
1342
1343/**
1344 * @brief set axis
1345 * @ingroup joints
1346 */
1347ODE_API void dJointSetHinge2Axis2 (dJointID, dReal x, dReal y, dReal z);
1348
1349/**
1350 * @brief set joint parameter
1351 * @ingroup joints
1352 */
1353ODE_API void dJointSetHinge2Param (dJointID, int parameter, dReal value);
1354
1355/**
1356 * @brief Applies torque1 about the hinge2's axis 1, torque2 about the
1357 * hinge2's axis 2.
1358 * @remarks This function is just a wrapper for dBodyAddTorque().
1359 * @ingroup joints
1360 */
1361ODE_API void dJointAddHinge2Torques(dJointID joint, dReal torque1, dReal torque2);
1362
1363/**
1364 * @brief set anchor
1365 * @ingroup joints
1366 */
1367ODE_API void dJointSetUniversalAnchor (dJointID, dReal x, dReal y, dReal z);
1368
1369/**
1370 * @brief set axis
1371 * @ingroup joints
1372 */
1373ODE_API void dJointSetUniversalAxis1 (dJointID, dReal x, dReal y, dReal z);
1374
1375/**
1376 * @brief set axis
1377 * @ingroup joints
1378 */
1379ODE_API void dJointSetUniversalAxis2 (dJointID, dReal x, dReal y, dReal z);
1380
1381/**
1382 * @brief set joint parameter
1383 * @ingroup joints
1384 */
1385ODE_API void dJointSetUniversalParam (dJointID, int parameter, dReal value);
1386
1387/**
1388 * @brief Applies torque1 about the universal's axis 1, torque2 about the
1389 * universal's axis 2.
1390 * @remarks This function is just a wrapper for dBodyAddTorque().
1391 * @ingroup joints
1392 */
1393ODE_API void dJointAddUniversalTorques(dJointID joint, dReal torque1, dReal torque2);
1394
1395
1396/**
1397 * @brief set anchor
1398 * @ingroup joints
1399 */
1400ODE_API void dJointSetPRAnchor (dJointID, dReal x, dReal y, dReal z);
1401
1402/**
1403 * @brief set the axis for the prismatic articulation
1404 * @ingroup joints
1405 */
1406ODE_API void dJointSetPRAxis1 (dJointID, dReal x, dReal y, dReal z);
1407
1408/**
1409 * @brief set the axis for the rotoide articulation
1410 * @ingroup joints
1411 */
1412ODE_API void dJointSetPRAxis2 (dJointID, dReal x, dReal y, dReal z);
1413
1414/**
1415 * @brief set joint parameter
1416 * @ingroup joints
1417 *
1418 * @note parameterX where X equal 2 refer to parameter for the rotoide articulation
1419 */
1420ODE_API void dJointSetPRParam (dJointID, int parameter, dReal value);
1421
1422/**
1423 * @brief Applies the torque about the rotoide axis of the PR joint
1424 *
1425 * That is, it applies a torque with specified magnitude in the direction
1426 * of the rotoide axis, to body 1, and with the same magnitude but in opposite
1427 * direction to body 2. This function is just a wrapper for dBodyAddTorque()}
1428 * @ingroup joints
1429 */
1430ODE_API void dJointAddPRTorque (dJointID j, dReal torque);
1431
1432
1433/**
1434 * @brief Call this on the fixed joint after it has been attached to
1435 * remember the current desired relative offset and desired relative
1436 * rotation between the bodies.
1437 * @ingroup joints
1438 */
1439ODE_API void dJointSetFixed (dJointID);
1440
1441/*
1442 * @brief Sets joint parameter
1443 *
1444 * @ingroup joints
1445 */
1446ODE_API void dJointSetFixedParam (dJointID, int parameter, dReal value);
1447
1448/**
1449 * @brief set the nr of axes
1450 * @param num 0..3
1451 * @ingroup joints
1452 */
1453ODE_API void dJointSetAMotorNumAxes (dJointID, int num);
1454
1455/**
1456 * @brief set axis
1457 * @ingroup joints
1458 */
1459ODE_API void dJointSetAMotorAxis (dJointID, int anum, int rel,
1460 dReal x, dReal y, dReal z);
1461
1462/**
1463 * @brief Tell the AMotor what the current angle is along axis anum.
1464 *
1465 * This function should only be called in dAMotorUser mode, because in this
1466 * mode the AMotor has no other way of knowing the joint angles.
1467 * The angle information is needed if stops have been set along the axis,
1468 * but it is not needed for axis motors.
1469 * @ingroup joints
1470 */
1471ODE_API void dJointSetAMotorAngle (dJointID, int anum, dReal angle);
1472
1473/**
1474 * @brief set joint parameter
1475 * @ingroup joints
1476 */
1477ODE_API void dJointSetAMotorParam (dJointID, int parameter, dReal value);
1478
1479/**
1480 * @brief set mode
1481 * @ingroup joints
1482 */
1483ODE_API void dJointSetAMotorMode (dJointID, int mode);
1484
1485/**
1486 * @brief Applies torque0 about the AMotor's axis 0, torque1 about the
1487 * AMotor's axis 1, and torque2 about the AMotor's axis 2.
1488 * @remarks
1489 * If the motor has fewer than three axes, the higher torques are ignored.
1490 * This function is just a wrapper for dBodyAddTorque().
1491 * @ingroup joints
1492 */
1493ODE_API void dJointAddAMotorTorques (dJointID, dReal torque1, dReal torque2, dReal torque3);
1494
1495/**
1496 * @brief Set the number of axes that will be controlled by the LMotor.
1497 * @param num can range from 0 (which effectively deactivates the joint) to 3.
1498 * @ingroup joints
1499 */
1500ODE_API void dJointSetLMotorNumAxes (dJointID, int num);
1501
1502/**
1503 * @brief Set the AMotor axes.
1504 * @param anum selects the axis to change (0,1 or 2).
1505 * @param rel Each axis can have one of three ``relative orientation'' modes
1506 * \li 0: The axis is anchored to the global frame.
1507 * \li 1: The axis is anchored to the first body.
1508 * \li 2: The axis is anchored to the second body.
1509 * @remarks The axis vector is always specified in global coordinates
1510 * regardless of the setting of rel.
1511 * @ingroup joints
1512 */
1513ODE_API void dJointSetLMotorAxis (dJointID, int anum, int rel, dReal x, dReal y, dReal z);
1514
1515/**
1516 * @brief set joint parameter
1517 * @ingroup joints
1518 */
1519ODE_API void dJointSetLMotorParam (dJointID, int parameter, dReal value);
1520
1521/**
1522 * @ingroup joints
1523 */
1524ODE_API void dJointSetPlane2DXParam (dJointID, int parameter, dReal value);
1525
1526/**
1527 * @ingroup joints
1528 */
1529
1530ODE_API void dJointSetPlane2DYParam (dJointID, int parameter, dReal value);
1531
1532/**
1533 * @ingroup joints
1534 */
1535ODE_API void dJointSetPlane2DAngleParam (dJointID, int parameter, dReal value);
1536
1537/**
1538 * @brief Get the joint anchor point, in world coordinates.
1539 *
1540 * This returns the point on body 1. If the joint is perfectly satisfied,
1541 * this will be the same as the point on body 2.
1542 */
1543ODE_API void dJointGetBallAnchor (dJointID, dVector3 result);
1544
1545/**
1546 * @brief Get the joint anchor point, in world coordinates.
1547 *
1548 * This returns the point on body 2. You can think of a ball and socket
1549 * joint as trying to keep the result of dJointGetBallAnchor() and
1550 * dJointGetBallAnchor2() the same. If the joint is perfectly satisfied,
1551 * this function will return the same value as dJointGetBallAnchor() to
1552 * within roundoff errors. dJointGetBallAnchor2() can be used, along with
1553 * dJointGetBallAnchor(), to see how far the joint has come apart.
1554 */
1555ODE_API void dJointGetBallAnchor2 (dJointID, dVector3 result);
1556
1557/**
1558 * @brief get joint parameter
1559 * @ingroup joints
1560 */
1561ODE_API dReal dJointGetBallParam (dJointID, int parameter);
1562
1563/**
1564 * @brief Get the hinge anchor point, in world coordinates.
1565 *
1566 * This returns the point on body 1. If the joint is perfectly satisfied,
1567 * this will be the same as the point on body 2.
1568 * @ingroup joints
1569 */
1570ODE_API void dJointGetHingeAnchor (dJointID, dVector3 result);
1571
1572/**
1573 * @brief Get the joint anchor point, in world coordinates.
1574 * @return The point on body 2. If the joint is perfectly satisfied,
1575 * this will return the same value as dJointGetHingeAnchor().
1576 * If not, this value will be slightly different.
1577 * This can be used, for example, to see how far the joint has come apart.
1578 * @ingroup joints
1579 */
1580ODE_API void dJointGetHingeAnchor2 (dJointID, dVector3 result);
1581
1582/**
1583 * @brief get axis
1584 * @ingroup joints
1585 */
1586ODE_API void dJointGetHingeAxis (dJointID, dVector3 result);
1587
1588/**
1589 * @brief get joint parameter
1590 * @ingroup joints
1591 */
1592ODE_API dReal dJointGetHingeParam (dJointID, int parameter);
1593
1594/**
1595 * @brief Get the hinge angle.
1596 *
1597 * The angle is measured between the two bodies, or between the body and
1598 * the static environment.
1599 * The angle will be between -pi..pi.
1600 * When the hinge anchor or axis is set, the current position of the attached
1601 * bodies is examined and that position will be the zero angle.
1602 * @ingroup joints
1603 */
1604ODE_API dReal dJointGetHingeAngle (dJointID);
1605
1606/**
1607 * @brief Get the hinge angle time derivative.
1608 * @ingroup joints
1609 */
1610ODE_API dReal dJointGetHingeAngleRate (dJointID);
1611
1612/**
1613 * @brief Get the slider linear position (i.e. the slider's extension)
1614 *
1615 * When the axis is set, the current position of the attached bodies is
1616 * examined and that position will be the zero position.
1617 * @ingroup joints
1618 */
1619ODE_API dReal dJointGetSliderPosition (dJointID);
1620
1621/**
1622 * @brief Get the slider linear position's time derivative.
1623 * @ingroup joints
1624 */
1625ODE_API dReal dJointGetSliderPositionRate (dJointID);
1626
1627/**
1628 * @brief Get the slider axis
1629 * @ingroup joints
1630 */
1631ODE_API void dJointGetSliderAxis (dJointID, dVector3 result);
1632
1633/**
1634 * @brief get joint parameter
1635 * @ingroup joints
1636 */
1637ODE_API dReal dJointGetSliderParam (dJointID, int parameter);
1638
1639/**
1640 * @brief Get the joint anchor point, in world coordinates.
1641 * @return the point on body 1. If the joint is perfectly satisfied,
1642 * this will be the same as the point on body 2.
1643 * @ingroup joints
1644 */
1645ODE_API void dJointGetHinge2Anchor (dJointID, dVector3 result);
1646
1647/**
1648 * @brief Get the joint anchor point, in world coordinates.
1649 * This returns the point on body 2. If the joint is perfectly satisfied,
1650 * this will return the same value as dJointGetHinge2Anchor.
1651 * If not, this value will be slightly different.
1652 * This can be used, for example, to see how far the joint has come apart.
1653 * @ingroup joints
1654 */
1655ODE_API void dJointGetHinge2Anchor2 (dJointID, dVector3 result);
1656
1657/**
1658 * @brief Get joint axis
1659 * @ingroup joints
1660 */
1661ODE_API void dJointGetHinge2Axis1 (dJointID, dVector3 result);
1662
1663/**
1664 * @brief Get joint axis
1665 * @ingroup joints
1666 */
1667ODE_API void dJointGetHinge2Axis2 (dJointID, dVector3 result);
1668
1669/**
1670 * @brief get joint parameter
1671 * @ingroup joints
1672 */
1673ODE_API dReal dJointGetHinge2Param (dJointID, int parameter);
1674
1675/**
1676 * @brief Get angle
1677 * @ingroup joints
1678 */
1679ODE_API dReal dJointGetHinge2Angle1 (dJointID);
1680
1681/**
1682 * @brief Get time derivative of angle
1683 * @ingroup joints
1684 */
1685ODE_API dReal dJointGetHinge2Angle1Rate (dJointID);
1686
1687/**
1688 * @brief Get time derivative of angle
1689 * @ingroup joints
1690 */
1691ODE_API dReal dJointGetHinge2Angle2Rate (dJointID);
1692
1693/**
1694 * @brief Get the joint anchor point, in world coordinates.
1695 * @return the point on body 1. If the joint is perfectly satisfied,
1696 * this will be the same as the point on body 2.
1697 * @ingroup joints
1698 */
1699ODE_API void dJointGetUniversalAnchor (dJointID, dVector3 result);
1700
1701/**
1702 * @brief Get the joint anchor point, in world coordinates.
1703 * @return This returns the point on body 2.
1704 * @remarks
1705 * You can think of the ball and socket part of a universal joint as
1706 * trying to keep the result of dJointGetBallAnchor() and
1707 * dJointGetBallAnchor2() the same. If the joint is
1708 * perfectly satisfied, this function will return the same value
1709 * as dJointGetUniversalAnchor() to within roundoff errors.
1710 * dJointGetUniversalAnchor2() can be used, along with
1711 * dJointGetUniversalAnchor(), to see how far the joint has come apart.
1712 * @ingroup joints
1713 */
1714ODE_API void dJointGetUniversalAnchor2 (dJointID, dVector3 result);
1715
1716/**
1717 * @brief Get axis
1718 * @ingroup joints
1719 */
1720ODE_API void dJointGetUniversalAxis1 (dJointID, dVector3 result);
1721
1722/**
1723 * @brief Get axis
1724 * @ingroup joints
1725 */
1726ODE_API void dJointGetUniversalAxis2 (dJointID, dVector3 result);
1727
1728
1729/**
1730 * @brief get joint parameter
1731 * @ingroup joints
1732 */
1733ODE_API dReal dJointGetUniversalParam (dJointID, int parameter);
1734
1735/**
1736 * @brief Get both angles at the same time.
1737 * @ingroup joints
1738 *
1739 * @param joint The universal joint for which we want to calculate the angles
1740 * @param angle1 The angle between the body1 and the axis 1
1741 * @param angle2 The angle between the body2 and the axis 2
1742 *
1743 * @note This function combine getUniversalAngle1 and getUniversalAngle2 together
1744 * and try to avoid redundant calculation
1745 */
1746ODE_API void dJointGetUniversalAngles (dJointID, dReal *angle1, dReal *angle2);
1747
1748/**
1749 * @brief Get angle
1750 * @ingroup joints
1751 */
1752ODE_API dReal dJointGetUniversalAngle1 (dJointID);
1753
1754/**
1755 * @brief Get angle
1756 * @ingroup joints
1757 */
1758ODE_API dReal dJointGetUniversalAngle2 (dJointID);
1759
1760/**
1761 * @brief Get time derivative of angle
1762 * @ingroup joints
1763 */
1764ODE_API dReal dJointGetUniversalAngle1Rate (dJointID);
1765
1766/**
1767 * @brief Get time derivative of angle
1768 * @ingroup joints
1769 */
1770ODE_API dReal dJointGetUniversalAngle2Rate (dJointID);
1771
1772
1773
1774/**
1775 * @brief Get the joint anchor point, in world coordinates.
1776 * @return the point on body 1. If the joint is perfectly satisfied,
1777 * this will be the same as the point on body 2.
1778 * @ingroup joints
1779 */
1780ODE_API void dJointGetPRAnchor (dJointID, dVector3 result);
1781
1782/**
1783 * @brief Get the PR linear position (i.e. the prismatic's extension)
1784 *
1785 * When the axis is set, the current position of the attached bodies is
1786 * examined and that position will be the zero position.
1787 *
1788 * The position is the "oriented" length between the
1789 * position = (Prismatic axis) dot_product [(body1 + offset) - (body2 + anchor2)]
1790 *
1791 * @ingroup joints
1792 */
1793ODE_API dReal dJointGetPRPosition (dJointID);
1794
1795/**
1796 * @brief Get the PR linear position's time derivative
1797 *
1798 * @ingroup joints
1799 */
1800ODE_API dReal dJointGetPRPositionRate (dJointID);
1801
1802
1803/**
1804 * @brief Get the prismatic axis
1805 * @ingroup joints
1806 */
1807ODE_API void dJointGetPRAxis1 (dJointID, dVector3 result);
1808
1809/**
1810 * @brief Get the Rotoide axis
1811 * @ingroup joints
1812 */
1813ODE_API void dJointGetPRAxis2 (dJointID, dVector3 result);
1814
1815/**
1816 * @brief get joint parameter
1817 * @ingroup joints
1818 */
1819ODE_API dReal dJointGetPRParam (dJointID, int parameter);
1820
1821
1822
1823/**
1824 * @brief Get the number of angular axes that will be controlled by the
1825 * AMotor.
1826 * @param num can range from 0 (which effectively deactivates the
1827 * joint) to 3.
1828 * This is automatically set to 3 in dAMotorEuler mode.
1829 * @ingroup joints
1830 */
1831ODE_API int dJointGetAMotorNumAxes (dJointID);
1832
1833/**
1834 * @brief Get the AMotor axes.
1835 * @param anum selects the axis to change (0,1 or 2).
1836 * @param rel Each axis can have one of three ``relative orientation'' modes.
1837 * \li 0: The axis is anchored to the global frame.
1838 * \li 1: The axis is anchored to the first body.
1839 * \li 2: The axis is anchored to the second body.
1840 * @ingroup joints
1841 */
1842ODE_API void dJointGetAMotorAxis (dJointID, int anum, dVector3 result);
1843
1844/**
1845 * @brief Get axis
1846 * @remarks
1847 * The axis vector is always specified in global coordinates regardless
1848 * of the setting of rel.
1849 * There are two GetAMotorAxis functions, one to return the axis and one to
1850 * return the relative mode.
1851 *
1852 * For dAMotorEuler mode:
1853 * \li Only axes 0 and 2 need to be set. Axis 1 will be determined
1854 automatically at each time step.
1855 * \li Axes 0 and 2 must be perpendicular to each other.
1856 * \li Axis 0 must be anchored to the first body, axis 2 must be anchored
1857 to the second body.
1858 * @ingroup joints
1859 */
1860ODE_API int dJointGetAMotorAxisRel (dJointID, int anum);
1861
1862/**
1863 * @brief Get the current angle for axis.
1864 * @remarks
1865 * In dAMotorUser mode this is simply the value that was set with
1866 * dJointSetAMotorAngle().
1867 * In dAMotorEuler mode this is the corresponding euler angle.
1868 * @ingroup joints
1869 */
1870ODE_API dReal dJointGetAMotorAngle (dJointID, int anum);
1871
1872/**
1873 * @brief Get the current angle rate for axis anum.
1874 * @remarks
1875 * In dAMotorUser mode this is always zero, as not enough information is
1876 * available.
1877 * In dAMotorEuler mode this is the corresponding euler angle rate.
1878 * @ingroup joints
1879 */
1880ODE_API dReal dJointGetAMotorAngleRate (dJointID, int anum);
1881
1882/**
1883 * @brief get joint parameter
1884 * @ingroup joints
1885 */
1886ODE_API dReal dJointGetAMotorParam (dJointID, int parameter);
1887
1888/**
1889 * @brief Get the angular motor mode.
1890 * @param mode must be one of the following constants:
1891 * \li dAMotorUser The AMotor axes and joint angle settings are entirely
1892 * controlled by the user. This is the default mode.
1893 * \li dAMotorEuler Euler angles are automatically computed.
1894 * The axis a1 is also automatically computed.
1895 * The AMotor axes must be set correctly when in this mode,
1896 * as described below.
1897 * When this mode is initially set the current relative orientations
1898 * of the bodies will correspond to all euler angles at zero.
1899 * @ingroup joints
1900 */
1901ODE_API int dJointGetAMotorMode (dJointID);
1902
1903/**
1904 * @brief Get nr of axes.
1905 * @ingroup joints
1906 */
1907ODE_API int dJointGetLMotorNumAxes (dJointID);
1908
1909/**
1910 * @brief Get axis.
1911 * @ingroup joints
1912 */
1913ODE_API void dJointGetLMotorAxis (dJointID, int anum, dVector3 result);
1914
1915/**
1916 * @brief get joint parameter
1917 * @ingroup joints
1918 */
1919ODE_API dReal dJointGetLMotorParam (dJointID, int parameter);
1920
1921/**
1922 * @brief get joint parameter
1923 * @ingroup joints
1924 */
1925ODE_API dReal dJointGetFixedParam (dJointID, int parameter);
1926
1927
1928/**
1929 * @ingroup joints
1930 */
1931ODE_API dJointID dConnectingJoint (dBodyID, dBodyID);
1932
1933/**
1934 * @ingroup joints
1935 */
1936ODE_API int dConnectingJointList (dBodyID, dBodyID, dJointID*);
1937
1938/**
1939 * @brief Utility function
1940 * @return 1 if the two bodies are connected together by
1941 * a joint, otherwise return 0.
1942 * @ingroup joints
1943 */
1944ODE_API int dAreConnected (dBodyID, dBodyID);
1945
1946/**
1947 * @brief Utility function
1948 * @return 1 if the two bodies are connected together by
1949 * a joint that does not have type @arg{joint_type}, otherwise return 0.
1950 * @param body1 A body to check.
1951 * @param body2 A body to check.
1952 * @param joint_type is a dJointTypeXXX constant.
1953 * This is useful for deciding whether to add contact joints between two bodies:
1954 * if they are already connected by non-contact joints then it may not be
1955 * appropriate to add contacts, however it is okay to add more contact between-
1956 * bodies that already have contacts.
1957 * @ingroup joints
1958 */
1959ODE_API int dAreConnectedExcluding (dBodyID body1, dBodyID body2, int joint_type);
1960
1961
1962#ifdef __cplusplus
1963}
1964#endif
1965
1966#endif
generated by cgit v1.1 at 2024-11-10 16:58:53 +0000