dali-physics/third-party/chipmunk2d/objectivec/include/ObjectiveChipmunk/ChipmunkConstraint.h

   1 /* Copyright (c) 2013 Scott Lembcke and Howling Moon Software
   2  *
   3  * Permission is hereby granted, free of charge, to any person obtaining a copy
   4  * of this software and associated documentation files (the "Software"), to deal
   5  * in the Software without restriction, including without limitation the rights
   6  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   7  * copies of the Software, and to permit persons to whom the Software is
   8  * furnished to do so, subject to the following conditions:
   9  *
  10  * The above copyright notice and this permission notice shall be included in
  11  * all copies or substantial portions of the Software.
  12  *
  13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  16  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  17  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  18  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  19  * SOFTWARE.
  20  */
  21
  22 /**
  23         Constraints connect two ChipmunkBody objects together. Most often constraints are simple joints, but can also be things like motors, friction generators or servos.
  24
  25         @htmlonly
  26         <object width="425" height="344">
  27                 <param name="movie" value="http://www.youtube.com/v/ZgJJZTS0aMM?fs=1&amp;hl=en_US&amp;rel=0"></param>
  28                 <param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param>
  29                 <embed src="http://www.youtube.com/v/ZgJJZTS0aMM?fs=1&amp;hl=en_US&amp;rel=0" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed>
  30         </object>
  31         @endhtmlonly
  32 */
  33 @interface ChipmunkConstraint : NSObject <ChipmunkBaseObject> {
  34 @private
  35         id _userData;
  36 }
  37
  38 /// Returns a pointer to the underlying cpConstraint C struct.
  39 @property(nonatomic, readonly) cpConstraint *constraint;
  40
  41 /// The first ChipmunkBody the constraint controls.
  42 @property(nonatomic, readonly) ChipmunkBody *bodyA;
  43
  44 /// The second ChipmunkBody the constraint controls.
  45 @property(nonatomic, readonly) ChipmunkBody *bodyB;
  46
  47 /// Get the ChipmunkConstraint object associciated with a cpConstraint pointer.
  48 /// Undefined if the cpConstraint wasn't created using Objective-Chipmunk.
  49 +(ChipmunkConstraint *)constraintFromCPConstraint:(cpConstraint *)constraint;
  50
  51 /**
  52         Maximum force this constraint is allowed to use (defalts to infinity).
  53         This allows joints to be pulled apart if too much force is applied to them.
  54         It also allows you to use constraints as force or friction generators for controlling bodies.
  55 */
  56 @property(nonatomic, assign) cpFloat maxForce;
  57
  58 /**
  59         The rate at which joint error is corrected.
  60         Defaults to pow(1.0 - 0.1, 60.0) meaning that it will correct 10% of the error every 1/60th of a second.
  61 */
  62 @property(nonatomic, assign) cpFloat errorBias;
  63
  64 /**
  65         Maximum rate (speed) that a joint can be corrected at (defaults to infinity).
  66         Setting this value to a finite value allows you to control a joint like a servo motor.
  67 */
  68 @property(nonatomic, assign) cpFloat maxBias;
  69
  70 /**
  71         Whether or not the connected bodies should checked for collisions.
  72         Collisions are filtered before calling callbacks.
  73         Defaults to TRUE.
  74 */
  75 @property(nonatomic, assign) BOOL collideBodies;
  76
  77 /// Get the most recent impulse applied by this constraint.
  78 @property(nonatomic, readonly) cpFloat impulse;
  79
  80 /// Get the space the body is added to.
  81 @property(nonatomic, readonly) ChipmunkSpace *space;
  82
  83 /**
  84         An object that this constraint is associated with. You can use this get a reference to your game object or controller object from within callbacks.
  85         @attention Like most @c delegate properties this is a weak reference and does not call @c retain. This prevents reference cycles from occuring.
  86 */
  87 @property(nonatomic, assign) id userData;
  88
  89 /// Override this method to update a constraints parameters just before running the physics each step.
  90 -(void)preSolve:(ChipmunkSpace *)space;
  91
  92 /// Override this method to poll values from a constraint each frame after the physics runs.
  93 /// This can be used to implement breakable joints for instance.
  94 -(void)postSolve:(ChipmunkSpace *)space;
  95
  96 @end
  97
  98
  99 /**
 100         Pin joints hold a set distance between points on two bodies.
 101         Think of them as connecting a solid pin or rod between the two anchor points.
 102 */
 103 @interface ChipmunkPinJoint : ChipmunkConstraint
 104
 105 /**
 106         Create an autoreleased pin joint between the two bodies with the given anchor points.
 107         The distance is calculated when the joint is initialized. It can be set explicitly using the property.
 108 */
 109 + (ChipmunkPinJoint *)pinJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB;
 110
 111 /**
 112         Initialize a pin joint between the two bodies with the given anchor points.
 113         The distance is calculated when the joint is initialized. It can be set explicitly using the property.
 114 */
 115 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB;
 116
 117 /// The anchor point on the first body.
 118 @property(nonatomic, assign) cpVect anchorA;
 119
 120 /// The anchor point on the second body.
 121 @property(nonatomic, assign) cpVect anchorB;
 122
 123 /// The distance between the two anchor points that the joint keeps.
 124 @property(nonatomic, assign) cpFloat dist;
 125
 126 @end
 127
 128
 129 /**
 130         Slide joints hold the distance between points on two bodies between a minimum and a maximum.
 131         Think of them as a telescoping ChipmunkPinJoint.
 132 */
 133 @interface ChipmunkSlideJoint : ChipmunkConstraint
 134
 135 /**
 136         Create an autoreleased slide joint between the two bodies with the given anchor points and distance range.
 137 */
 138 + (ChipmunkSlideJoint *)slideJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB min:(cpFloat)min max:(cpFloat)max;
 139
 140 /**
 141         Initialize a slide joint between the two bodies with the given anchor points and distance range.
 142 */
 143 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB min:(cpFloat)min max:(cpFloat)max;
 144
 145 /// The anchor point on the first body.
 146 @property(nonatomic, assign) cpVect anchorA;
 147
 148 /// The anchor point on the second body.
 149 @property(nonatomic, assign) cpVect anchorB;
 150
 151 /// The minimum allowed distance between anchor points.
 152 @property(nonatomic, assign) cpFloat min;
 153
 154 /// The maximum allowed distance between anchor points.
 155 @property(nonatomic, assign) cpFloat max;
 156
 157 @end
 158
 159
 160 /**
 161         Pivot joints hold two points on two bodies together allowing them to rotate freely around the pivot.
 162 */
 163 @interface ChipmunkPivotJoint : ChipmunkConstraint
 164
 165 /**
 166         Create an autoreleased pivot joint between the two bodies with the two anchor points.
 167         Make sure you have the bodies in the right place as the joint will fix itself as soon as you start simulating the space.
 168 */
 169 + (ChipmunkPivotJoint *)pivotJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB;
 170
 171 /**
 172         Create an autoreleased pivot joint between the two bodies by calculating the anchor points from the pivot point given in absolute coordinates.
 173 */
 174 + (ChipmunkPivotJoint *)pivotJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b pivot:(cpVect)pivot;
 175
 176 /**
 177         Initialize a pivot joint between the two bodies with the two anchor points.
 178         Make sure you have the bodies in the right place as the joint will fix itself as soon as you start simulating the space.
 179 */
 180 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB;
 181
 182 /**
 183         Initialize a pivot joint between the two bodies by calculating the anchor points from the pivot point given in absolute coordinates.
 184 */
 185 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b pivot:(cpVect)pivot;
 186
 187 /// The anchor point on the first body.
 188 @property(nonatomic, assign) cpVect anchorA;
 189
 190 /// The anchor point on the second body.
 191 @property(nonatomic, assign) cpVect anchorB;
 192
 193 @end
 194
 195
 196 /**
 197         Groove joints hold a pivot point on one body to line along a line segment on another like a pin in a groove.
 198 */
 199 @interface ChipmunkGrooveJoint : ChipmunkConstraint
 200
 201 /**
 202         Create an autoreleased groove joint between the two bodies.
 203         Make sure you have the bodies in the right place as the joint will snap into shape as soon as you start simulating the space.
 204         @param grooveA The start of the line segment on the first body.
 205         @param grooveB The end of the line segment on the first body.
 206         @param anchorB The anchor point on the second body that is held to the line segment on the first.
 207 */
 208 + (ChipmunkGrooveJoint *)grooveJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b grooveA:(cpVect)grooveA grooveB:(cpVect)grooveB anchorB:(cpVect)anchorB;
 209
 210 /**
 211         Initialize a groove joint between the two bodies.
 212         Make sure you have the bodies in the right place as the joint will snap into shape as soon as you start simulating the space.
 213         @param grooveA The start of the line segment on the first body.
 214         @param grooveB The end of the line segment on the first body.
 215         @param anchorB The anchor point on the second body that is held to the line segment on the first.
 216 */
 217 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b grooveA:(cpVect)grooveA grooveB:(cpVect)grooveB anchorB:(cpVect)anchorB;
 218
 219 /// The start point of the groove on the first body.
 220 @property(nonatomic, assign) cpVect grooveA;
 221 /// The end point of the groove on the first body.
 222 @property(nonatomic, assign) cpVect grooveB;
 223
 224 /// The anchor point on the second body.
 225 @property(nonatomic, assign) cpVect anchorB;
 226
 227 @end
 228
 229
 230 /**
 231         A spring with a damper.
 232         While a spring is not technically a constraint, the damper is. The spring forces are simply a convenience.
 233 */
 234 @interface ChipmunkDampedSpring : ChipmunkConstraint
 235
 236 /**
 237         Create an autoreleased damped spring between two bodies at the given anchor points.
 238         @param restLength The length the spring wants to contract or expand to.
 239         @param stiffness The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 240         @param damping The amount of viscous damping to apply.
 241 */
 242 + (ChipmunkDampedSpring *)dampedSpringWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB restLength:(cpFloat)restLength stiffness:(cpFloat)stiffness damping:(cpFloat)damping;
 243
 244 /**
 245         Initialize a damped spring between two bodies at the given anchor points.
 246         @param restLength The length the spring wants to contract or expand to.
 247         @param stiffness The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 248         @param damping The amount of viscous damping to apply.
 249 */
 250 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b anchorA:(cpVect)anchorA anchorB:(cpVect)anchorB restLength:(cpFloat)restLength stiffness:(cpFloat)stiffness damping:(cpFloat)damping;
 251
 252 /// The anchor point on the first body.
 253 @property(nonatomic, assign) cpVect anchorA;
 254
 255 /// The anchor point on the second body.
 256 @property(nonatomic, assign) cpVect anchorB;
 257
 258 /// The length the spring wants to contract or expand to.
 259 @property(nonatomic, assign) cpFloat restLength;
 260
 261 /// The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 262 @property(nonatomic, assign) cpFloat stiffness;
 263
 264 /// The amount of viscous damping to apply.
 265 @property(nonatomic, assign) cpFloat damping;
 266
 267 @end
 268
 269
 270 /**
 271         Like a ChipmunkDampedSpring, but operates in a rotational fashion.
 272 */
 273 @interface ChipmunkDampedRotarySpring : ChipmunkConstraint
 274
 275
 276 /**
 277         Create an autoreleased damped rotary spring between the given bodies.
 278         @param restAngle The angular offset in radians the spring attempts to keep between the two bodies.
 279         @param stiffness The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 280         @param damping The amount of viscous damping to apply.
 281 */
 282 + (ChipmunkDampedRotarySpring *)dampedRotarySpringWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b restAngle:(cpFloat)restAngle stiffness:(cpFloat)stiffness damping:(cpFloat)damping;
 283
 284 /**
 285         Initialize a damped rotary spring between the given bodies.
 286         @param restAngle The angular offset in radians the spring attempts to keep between the two bodies.
 287         @param stiffness The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 288         @param damping The amount of viscous damping to apply.
 289 */
 290 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b restAngle:(cpFloat)restAngle stiffness:(cpFloat)stiffness damping:(cpFloat)damping;
 291
 292 /// The angular offset the spring attempts to keep between the two bodies.
 293 @property(nonatomic, assign) cpFloat restAngle;
 294
 295 /// The <a href="http://en.wikipedia.org/wiki/Young's_modulus">young's modulus</a> of the spring.
 296 @property(nonatomic, assign) cpFloat stiffness;
 297
 298 /// The amount of viscous damping to apply.
 299 @property(nonatomic, assign) cpFloat damping;
 300
 301 @end
 302
 303
 304 /**
 305         Constrains the angle between two bodies.
 306         This joint is often used in conjuction with a separate ChipmunkPivotJoint in order to limit the rotation around the pivot.
 307 */
 308 @interface ChipmunkRotaryLimitJoint : ChipmunkConstraint
 309
 310 /**
 311         Create an autoreleased rotary limit joint between the two bodies and angular range in radians.
 312         Make sure you have the bodies in the right place as the joint will snap into shape as soon as you start simulating the space.
 313 */
 314 + (ChipmunkRotaryLimitJoint *)rotaryLimitJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b min:(cpFloat)min max:(cpFloat)max;
 315
 316 /**
 317         Create an autoreleased rotary limit joint between the two bodies and angular range in radians.
 318         Make sure you have the bodies in the right place as the joint will snap into shape as soon as you start simulating the space.
 319 */
 320 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b min:(cpFloat)min max:(cpFloat)max;
 321
 322 /// The minimum angular delta of the joint in radians.
 323 @property(nonatomic, assign) cpFloat min;
 324
 325 /// The maximum angular delta of the joint in radians.
 326 @property(nonatomic, assign) cpFloat max;
 327
 328 @end
 329
 330
 331 /**
 332         Simple motors make two objects spin relative to each other.
 333         They are most often used with the ChipmunkConstraint.maxForce property set to a finite value.
 334 */
 335 @interface ChipmunkSimpleMotor : ChipmunkConstraint
 336
 337 /// Create an autoreleased simple motor between the given bodies and relative rotation rate in radians per second.
 338 + (ChipmunkSimpleMotor *)simpleMotorWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b rate:(cpFloat)rate;
 339
 340 /// Initialize a simple motor between the given bodies and relative rotation rate in radians per second.
 341 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b rate:(cpFloat)rate;
 342
 343 /// The relative rotation speed of the two bodies in radians per second.
 344 @property(nonatomic, assign) cpFloat rate;
 345
 346 @end
 347
 348
 349 /**
 350         Gear joints constrain the rotational speed of one body to another.
 351         A ratio of 1.0 will lock the rotation of two bodies together, and negative ratios will cause them to spin in opposite directions.
 352         You can also use gear joints as rotary servos by setting ChipmunkConstraint.maxForce and ChipmunkConstraint.maxBias to finite values and changing the ChipmunkGearJoint.phase property.
 353 */
 354 @interface ChipmunkGearJoint : ChipmunkConstraint
 355
 356 /**
 357         Create an autoreleased gear joint between the given bodies.
 358         @param phase The angular offset.
 359         @param ratio The ratio of the rotational speeds.
 360 */
 361 + (ChipmunkGearJoint *)gearJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b phase:(cpFloat)phase ratio:(cpFloat)ratio;
 362
 363 /**
 364         Initialize a gear joint between the given bodies.
 365         @param phase The angular offset in radians.
 366         @param ratio The ratio of the rotational speeds.
 367 */
 368 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b phase:(cpFloat)phase ratio:(cpFloat)ratio;
 369
 370 /// The angular offset in radians.
 371 @property(nonatomic, assign) cpFloat phase;
 372 /// The ratio of the rotational speeds.
 373 @property(nonatomic, assign) cpFloat ratio;
 374
 375 @end
 376
 377 /**
 378         Ratchet joints create rotary ratches similar to a socket wrench.
 379 */
 380 @interface ChipmunkRatchetJoint : ChipmunkConstraint
 381
 382 /**
 383         Create an autoreleased ratchet joint between the given bodies.
 384         @param phase The angular offset of the ratchet positions in radians.
 385         @param ratchet The angle in radians of each ratchet position. Negative values cause the ratchet to operate in the opposite direction.
 386 */
 387 + (ChipmunkRatchetJoint *)ratchetJointWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b phase:(cpFloat)phase ratchet:(cpFloat)ratchet;
 388
 389 /**
 390         Initialize a ratchet joint between the given bodies.
 391         @param phase The angular offset of the ratchet positions in radians.
 392         @param ratchet The angle in radians of each ratchet position. Negative values cause the ratchet to operate in the opposite direction.
 393 */
 394 - (id)initWithBodyA:(ChipmunkBody *)a bodyB:(ChipmunkBody *)b phase:(cpFloat)phase ratchet:(cpFloat)ratchet;
 395
 396 /// The current ratchet position in radians.
 397 @property(nonatomic, assign) cpFloat angle;
 398
 399 /// The angular offset of the ratchet positions in radians
 400 @property(nonatomic, assign) cpFloat phase;
 401
 402 /// The angle in radians of each ratchet position. Negative values cause the ratchet to operate in the opposite direction.
 403 @property(nonatomic, assign) cpFloat ratchet;
 404
 405 @end