box2d.h (52817B)
1 // SPDX-FileCopyrightText: 2023 Erin Catto 2 // SPDX-License-Identifier: MIT 3 4 #pragma once 5 6 #include "base.h" 7 #include "collision.h" 8 #include "id.h" 9 #include "types.h" 10 11 #include <stdbool.h> 12 13 /** 14 * @defgroup world World 15 * These functions allow you to create a simulation world. 16 * 17 * You can add rigid bodies and joint constraints to the world and run the simulation. You can get contact 18 * information to get contact points and normals as well as events. You can query to world, checking for overlaps and casting rays 19 * or shapes. There is also debugging information such as debug draw, timing information, and counters. You can find documentation 20 * here: https://box2d.org/ 21 * @{ 22 */ 23 24 /// Create a world for rigid body simulation. A world contains bodies, shapes, and constraints. You make create 25 /// up to 128 worlds. Each world is completely independent and may be simulated in parallel. 26 /// @return the world id. 27 B2_API b2WorldId b2CreateWorld( const b2WorldDef* def ); 28 29 /// Destroy a world 30 B2_API void b2DestroyWorld( b2WorldId worldId ); 31 32 /// World id validation. Provides validation for up to 64K allocations. 33 B2_API bool b2World_IsValid( b2WorldId id ); 34 35 /// Simulate a world for one time step. This performs collision detection, integration, and constraint solution. 36 /// @param worldId The world to simulate 37 /// @param timeStep The amount of time to simulate, this should be a fixed number. Usually 1/60. 38 /// @param subStepCount The number of sub-steps, increasing the sub-step count can increase accuracy. Usually 4. 39 B2_API void b2World_Step( b2WorldId worldId, float timeStep, int subStepCount ); 40 41 /// Call this to draw shapes and other debug draw data 42 B2_API void b2World_Draw( b2WorldId worldId, b2DebugDraw* draw ); 43 44 /// Get the body events for the current time step. The event data is transient. Do not store a reference to this data. 45 B2_API b2BodyEvents b2World_GetBodyEvents( b2WorldId worldId ); 46 47 /// Get sensor events for the current time step. The event data is transient. Do not store a reference to this data. 48 B2_API b2SensorEvents b2World_GetSensorEvents( b2WorldId worldId ); 49 50 /// Get contact events for this current time step. The event data is transient. Do not store a reference to this data. 51 B2_API b2ContactEvents b2World_GetContactEvents( b2WorldId worldId ); 52 53 /// Overlap test for all shapes that *potentially* overlap the provided AABB 54 B2_API b2TreeStats b2World_OverlapAABB( b2WorldId worldId, b2AABB aabb, b2QueryFilter filter, b2OverlapResultFcn* fcn, 55 void* context ); 56 57 /// Overlap test for for all shapes that overlap the provided point. 58 B2_API b2TreeStats b2World_OverlapPoint( b2WorldId worldId, b2Vec2 point, b2Transform transform, 59 b2QueryFilter filter, b2OverlapResultFcn* fcn, void* context ); 60 61 /// Overlap test for for all shapes that overlap the provided circle. A zero radius may be used for a point query. 62 B2_API b2TreeStats b2World_OverlapCircle( b2WorldId worldId, const b2Circle* circle, b2Transform transform, 63 b2QueryFilter filter, b2OverlapResultFcn* fcn, void* context ); 64 65 /// Overlap test for all shapes that overlap the provided capsule 66 B2_API b2TreeStats b2World_OverlapCapsule( b2WorldId worldId, const b2Capsule* capsule, b2Transform transform, 67 b2QueryFilter filter, b2OverlapResultFcn* fcn, void* context ); 68 69 /// Overlap test for all shapes that overlap the provided polygon 70 B2_API b2TreeStats b2World_OverlapPolygon( b2WorldId worldId, const b2Polygon* polygon, b2Transform transform, 71 b2QueryFilter filter, b2OverlapResultFcn* fcn, void* context ); 72 73 /// Cast a ray into the world to collect shapes in the path of the ray. 74 /// Your callback function controls whether you get the closest point, any point, or n-points. 75 /// The ray-cast ignores shapes that contain the starting point. 76 /// @note The callback function may receive shapes in any order 77 /// @param worldId The world to cast the ray against 78 /// @param origin The start point of the ray 79 /// @param translation The translation of the ray from the start point to the end point 80 /// @param filter Contains bit flags to filter unwanted shapes from the results 81 /// @param fcn A user implemented callback function 82 /// @param context A user context that is passed along to the callback function 83 /// @return traversal performance counters 84 B2_API b2TreeStats b2World_CastRay( b2WorldId worldId, b2Vec2 origin, b2Vec2 translation, b2QueryFilter filter, 85 b2CastResultFcn* fcn, void* context ); 86 87 /// Cast a ray into the world to collect the closest hit. This is a convenience function. 88 /// This is less general than b2World_CastRay() and does not allow for custom filtering. 89 B2_API b2RayResult b2World_CastRayClosest( b2WorldId worldId, b2Vec2 origin, b2Vec2 translation, b2QueryFilter filter ); 90 91 /// Cast a circle through the world. Similar to a cast ray except that a circle is cast instead of a point. 92 /// @see b2World_CastRay 93 B2_API b2TreeStats b2World_CastCircle( b2WorldId worldId, const b2Circle* circle, b2Transform originTransform, 94 b2Vec2 translation, b2QueryFilter filter, b2CastResultFcn* fcn, void* context ); 95 96 /// Cast a capsule through the world. Similar to a cast ray except that a capsule is cast instead of a point. 97 /// @see b2World_CastRay 98 B2_API b2TreeStats b2World_CastCapsule( b2WorldId worldId, const b2Capsule* capsule, b2Transform originTransform, 99 b2Vec2 translation, b2QueryFilter filter, b2CastResultFcn* fcn, void* context ); 100 101 /// Cast a polygon through the world. Similar to a cast ray except that a polygon is cast instead of a point. 102 /// @see b2World_CastRay 103 B2_API b2TreeStats b2World_CastPolygon( b2WorldId worldId, const b2Polygon* polygon, b2Transform originTransform, 104 b2Vec2 translation, b2QueryFilter filter, b2CastResultFcn* fcn, void* context ); 105 106 /// Enable/disable sleep. If your application does not need sleeping, you can gain some performance 107 /// by disabling sleep completely at the world level. 108 /// @see b2WorldDef 109 B2_API void b2World_EnableSleeping( b2WorldId worldId, bool flag ); 110 111 /// Is body sleeping enabled? 112 B2_API bool b2World_IsSleepingEnabled( b2WorldId worldId ); 113 114 /// Enable/disable continuous collision between dynamic and static bodies. Generally you should keep continuous 115 /// collision enabled to prevent fast moving objects from going through static objects. The performance gain from 116 /// disabling continuous collision is minor. 117 /// @see b2WorldDef 118 B2_API void b2World_EnableContinuous( b2WorldId worldId, bool flag ); 119 120 /// Is continuous collision enabled? 121 B2_API bool b2World_IsContinuousEnabled( b2WorldId worldId ); 122 123 /// Adjust the restitution threshold. It is recommended not to make this value very small 124 /// because it will prevent bodies from sleeping. Usually in meters per second. 125 /// @see b2WorldDef 126 B2_API void b2World_SetRestitutionThreshold( b2WorldId worldId, float value ); 127 128 /// Get the the restitution speed threshold. Usually in meters per second. 129 B2_API float b2World_GetRestitutionThreshold( b2WorldId worldId ); 130 131 /// Adjust the hit event threshold. This controls the collision speed needed to generate a b2ContactHitEvent. 132 /// Usually in meters per second. 133 /// @see b2WorldDef::hitEventThreshold 134 B2_API void b2World_SetHitEventThreshold( b2WorldId worldId, float value ); 135 136 /// Get the the hit event speed threshold. Usually in meters per second. 137 B2_API float b2World_GetHitEventThreshold( b2WorldId worldId ); 138 139 /// Register the custom filter callback. This is optional. 140 B2_API void b2World_SetCustomFilterCallback( b2WorldId worldId, b2CustomFilterFcn* fcn, void* context ); 141 142 /// Register the pre-solve callback. This is optional. 143 B2_API void b2World_SetPreSolveCallback( b2WorldId worldId, b2PreSolveFcn* fcn, void* context ); 144 145 /// Set the gravity vector for the entire world. Box2D has no concept of an up direction and this 146 /// is left as a decision for the application. Usually in m/s^2. 147 /// @see b2WorldDef 148 B2_API void b2World_SetGravity( b2WorldId worldId, b2Vec2 gravity ); 149 150 /// Get the gravity vector 151 B2_API b2Vec2 b2World_GetGravity( b2WorldId worldId ); 152 153 /// Apply a radial explosion 154 /// @param worldId The world id 155 /// @param explosionDef The explosion definition 156 B2_API void b2World_Explode( b2WorldId worldId, const b2ExplosionDef* explosionDef ); 157 158 /// Adjust contact tuning parameters 159 /// @param worldId The world id 160 /// @param hertz The contact stiffness (cycles per second) 161 /// @param dampingRatio The contact bounciness with 1 being critical damping (non-dimensional) 162 /// @param pushSpeed The maximum contact constraint push out speed (meters per second) 163 /// @note Advanced feature 164 B2_API void b2World_SetContactTuning( b2WorldId worldId, float hertz, float dampingRatio, float pushSpeed ); 165 166 /// Adjust joint tuning parameters 167 /// @param worldId The world id 168 /// @param hertz The contact stiffness (cycles per second) 169 /// @param dampingRatio The contact bounciness with 1 being critical damping (non-dimensional) 170 /// @note Advanced feature 171 B2_API void b2World_SetJointTuning( b2WorldId worldId, float hertz, float dampingRatio ); 172 173 /// Set the maximum linear speed. Usually in m/s. 174 B2_API void b2World_SetMaximumLinearSpeed( b2WorldId worldId, float maximumLinearSpeed ); 175 176 /// Get the maximum linear speed. Usually in m/s. 177 B2_API float b2World_GetMaximumLinearSpeed( b2WorldId worldId ); 178 179 /// Enable/disable constraint warm starting. Advanced feature for testing. Disabling 180 /// sleeping greatly reduces stability and provides no performance gain. 181 B2_API void b2World_EnableWarmStarting( b2WorldId worldId, bool flag ); 182 183 /// Is constraint warm starting enabled? 184 B2_API bool b2World_IsWarmStartingEnabled( b2WorldId worldId ); 185 186 /// Get the number of awake bodies. 187 B2_API int b2World_GetAwakeBodyCount( b2WorldId worldId ); 188 189 /// Get the current world performance profile 190 B2_API b2Profile b2World_GetProfile( b2WorldId worldId ); 191 192 /// Get world counters and sizes 193 B2_API b2Counters b2World_GetCounters( b2WorldId worldId ); 194 195 /// Set the user data pointer. 196 B2_API void b2World_SetUserData( b2WorldId worldId, void* userData ); 197 198 /// Get the user data pointer. 199 B2_API void* b2World_GetUserData( b2WorldId worldId ); 200 201 /// Set the friction callback. Passing NULL resets to default. 202 B2_API void b2World_SetFrictionCallback( b2WorldId worldId, b2FrictionCallback* callback ); 203 204 /// Set the restitution callback. Passing NULL resets to default. 205 B2_API void b2World_SetRestitutionCallback( b2WorldId worldId, b2RestitutionCallback* callback ); 206 207 /// Dump memory stats to box2d_memory.txt 208 B2_API void b2World_DumpMemoryStats( b2WorldId worldId ); 209 210 /// This is for internal testing 211 B2_API void b2World_RebuildStaticTree( b2WorldId worldId ); 212 213 /// This is for internal testing 214 B2_API void b2World_EnableSpeculative( b2WorldId worldId, bool flag ); 215 216 /** @} */ 217 218 /** 219 * @defgroup body Body 220 * This is the body API. 221 * @{ 222 */ 223 224 /// Create a rigid body given a definition. No reference to the definition is retained. So you can create the definition 225 /// on the stack and pass it as a pointer. 226 /// @code{.c} 227 /// b2BodyDef bodyDef = b2DefaultBodyDef(); 228 /// b2BodyId myBodyId = b2CreateBody(myWorldId, &bodyDef); 229 /// @endcode 230 /// @warning This function is locked during callbacks. 231 B2_API b2BodyId b2CreateBody( b2WorldId worldId, const b2BodyDef* def ); 232 233 /// Destroy a rigid body given an id. This destroys all shapes and joints attached to the body. 234 /// Do not keep references to the associated shapes and joints. 235 B2_API void b2DestroyBody( b2BodyId bodyId ); 236 237 /// Body identifier validation. Can be used to detect orphaned ids. Provides validation for up to 64K allocations. 238 B2_API bool b2Body_IsValid( b2BodyId id ); 239 240 /// Get the body type: static, kinematic, or dynamic 241 B2_API b2BodyType b2Body_GetType( b2BodyId bodyId ); 242 243 /// Change the body type. This is an expensive operation. This automatically updates the mass 244 /// properties regardless of the automatic mass setting. 245 B2_API void b2Body_SetType( b2BodyId bodyId, b2BodyType type ); 246 247 /// Set the body name. Up to 31 characters excluding 0 termination. 248 B2_API void b2Body_SetName( b2BodyId bodyId, const char* name ); 249 250 /// Get the body name. May be null. 251 B2_API const char* b2Body_GetName( b2BodyId bodyId ); 252 253 /// Set the user data for a body 254 B2_API void b2Body_SetUserData( b2BodyId bodyId, void* userData ); 255 256 /// Get the user data stored in a body 257 B2_API void* b2Body_GetUserData( b2BodyId bodyId ); 258 259 /// Get the world position of a body. This is the location of the body origin. 260 B2_API b2Vec2 b2Body_GetPosition( b2BodyId bodyId ); 261 262 /// Get the world rotation of a body as a cosine/sine pair (complex number) 263 B2_API b2Rot b2Body_GetRotation( b2BodyId bodyId ); 264 265 /// Get the world transform of a body. 266 B2_API b2Transform b2Body_GetTransform( b2BodyId bodyId ); 267 268 /// Set the world transform of a body. This acts as a teleport and is fairly expensive. 269 /// @note Generally you should create a body with then intended transform. 270 /// @see b2BodyDef::position and b2BodyDef::angle 271 B2_API void b2Body_SetTransform( b2BodyId bodyId, b2Vec2 position, b2Rot rotation ); 272 273 /// Get a local point on a body given a world point 274 B2_API b2Vec2 b2Body_GetLocalPoint( b2BodyId bodyId, b2Vec2 worldPoint ); 275 276 /// Get a world point on a body given a local point 277 B2_API b2Vec2 b2Body_GetWorldPoint( b2BodyId bodyId, b2Vec2 localPoint ); 278 279 /// Get a local vector on a body given a world vector 280 B2_API b2Vec2 b2Body_GetLocalVector( b2BodyId bodyId, b2Vec2 worldVector ); 281 282 /// Get a world vector on a body given a local vector 283 B2_API b2Vec2 b2Body_GetWorldVector( b2BodyId bodyId, b2Vec2 localVector ); 284 285 /// Get the linear velocity of a body's center of mass. Usually in meters per second. 286 B2_API b2Vec2 b2Body_GetLinearVelocity( b2BodyId bodyId ); 287 288 /// Get the angular velocity of a body in radians per second 289 B2_API float b2Body_GetAngularVelocity( b2BodyId bodyId ); 290 291 /// Set the linear velocity of a body. Usually in meters per second. 292 B2_API void b2Body_SetLinearVelocity( b2BodyId bodyId, b2Vec2 linearVelocity ); 293 294 /// Set the angular velocity of a body in radians per second 295 B2_API void b2Body_SetAngularVelocity( b2BodyId bodyId, float angularVelocity ); 296 297 /// Get the linear velocity of a local point attached to a body. Usually in meters per second. 298 B2_API b2Vec2 b2Body_GetLocalPointVelocity( b2BodyId bodyId, b2Vec2 localPoint ); 299 300 /// Get the linear velocity of a world point attached to a body. Usually in meters per second. 301 B2_API b2Vec2 b2Body_GetWorldPointVelocity( b2BodyId bodyId, b2Vec2 worldPoint ); 302 303 /// Apply a force at a world point. If the force is not applied at the center of mass, 304 /// it will generate a torque and affect the angular velocity. This optionally wakes up the body. 305 /// The force is ignored if the body is not awake. 306 /// @param bodyId The body id 307 /// @param force The world force vector, usually in newtons (N) 308 /// @param point The world position of the point of application 309 /// @param wake Option to wake up the body 310 B2_API void b2Body_ApplyForce( b2BodyId bodyId, b2Vec2 force, b2Vec2 point, bool wake ); 311 312 /// Apply a force to the center of mass. This optionally wakes up the body. 313 /// The force is ignored if the body is not awake. 314 /// @param bodyId The body id 315 /// @param force the world force vector, usually in newtons (N). 316 /// @param wake also wake up the body 317 B2_API void b2Body_ApplyForceToCenter( b2BodyId bodyId, b2Vec2 force, bool wake ); 318 319 /// Apply a torque. This affects the angular velocity without affecting the linear velocity. 320 /// This optionally wakes the body. The torque is ignored if the body is not awake. 321 /// @param bodyId The body id 322 /// @param torque about the z-axis (out of the screen), usually in N*m. 323 /// @param wake also wake up the body 324 B2_API void b2Body_ApplyTorque( b2BodyId bodyId, float torque, bool wake ); 325 326 /// Apply an impulse at a point. This immediately modifies the velocity. 327 /// It also modifies the angular velocity if the point of application 328 /// is not at the center of mass. This optionally wakes the body. 329 /// The impulse is ignored if the body is not awake. 330 /// @param bodyId The body id 331 /// @param impulse the world impulse vector, usually in N*s or kg*m/s. 332 /// @param point the world position of the point of application. 333 /// @param wake also wake up the body 334 /// @warning This should be used for one-shot impulses. If you need a steady force, 335 /// use a force instead, which will work better with the sub-stepping solver. 336 B2_API void b2Body_ApplyLinearImpulse( b2BodyId bodyId, b2Vec2 impulse, b2Vec2 point, bool wake ); 337 338 /// Apply an impulse to the center of mass. This immediately modifies the velocity. 339 /// The impulse is ignored if the body is not awake. This optionally wakes the body. 340 /// @param bodyId The body id 341 /// @param impulse the world impulse vector, usually in N*s or kg*m/s. 342 /// @param wake also wake up the body 343 /// @warning This should be used for one-shot impulses. If you need a steady force, 344 /// use a force instead, which will work better with the sub-stepping solver. 345 B2_API void b2Body_ApplyLinearImpulseToCenter( b2BodyId bodyId, b2Vec2 impulse, bool wake ); 346 347 /// Apply an angular impulse. The impulse is ignored if the body is not awake. 348 /// This optionally wakes the body. 349 /// @param bodyId The body id 350 /// @param impulse the angular impulse, usually in units of kg*m*m/s 351 /// @param wake also wake up the body 352 /// @warning This should be used for one-shot impulses. If you need a steady force, 353 /// use a force instead, which will work better with the sub-stepping solver. 354 B2_API void b2Body_ApplyAngularImpulse( b2BodyId bodyId, float impulse, bool wake ); 355 356 /// Get the mass of the body, usually in kilograms 357 B2_API float b2Body_GetMass( b2BodyId bodyId ); 358 359 /// Get the rotational inertia of the body, usually in kg*m^2 360 B2_API float b2Body_GetRotationalInertia( b2BodyId bodyId ); 361 362 /// Get the center of mass position of the body in local space 363 B2_API b2Vec2 b2Body_GetLocalCenterOfMass( b2BodyId bodyId ); 364 365 /// Get the center of mass position of the body in world space 366 B2_API b2Vec2 b2Body_GetWorldCenterOfMass( b2BodyId bodyId ); 367 368 /// Override the body's mass properties. Normally this is computed automatically using the 369 /// shape geometry and density. This information is lost if a shape is added or removed or if the 370 /// body type changes. 371 B2_API void b2Body_SetMassData( b2BodyId bodyId, b2MassData massData ); 372 373 /// Get the mass data for a body 374 B2_API b2MassData b2Body_GetMassData( b2BodyId bodyId ); 375 376 /// This update the mass properties to the sum of the mass properties of the shapes. 377 /// This normally does not need to be called unless you called SetMassData to override 378 /// the mass and you later want to reset the mass. 379 /// You may also use this when automatic mass computation has been disabled. 380 /// You should call this regardless of body type. 381 B2_API void b2Body_ApplyMassFromShapes( b2BodyId bodyId ); 382 383 /// Adjust the linear damping. Normally this is set in b2BodyDef before creation. 384 B2_API void b2Body_SetLinearDamping( b2BodyId bodyId, float linearDamping ); 385 386 /// Get the current linear damping. 387 B2_API float b2Body_GetLinearDamping( b2BodyId bodyId ); 388 389 /// Adjust the angular damping. Normally this is set in b2BodyDef before creation. 390 B2_API void b2Body_SetAngularDamping( b2BodyId bodyId, float angularDamping ); 391 392 /// Get the current angular damping. 393 B2_API float b2Body_GetAngularDamping( b2BodyId bodyId ); 394 395 /// Adjust the gravity scale. Normally this is set in b2BodyDef before creation. 396 /// @see b2BodyDef::gravityScale 397 B2_API void b2Body_SetGravityScale( b2BodyId bodyId, float gravityScale ); 398 399 /// Get the current gravity scale 400 B2_API float b2Body_GetGravityScale( b2BodyId bodyId ); 401 402 /// @return true if this body is awake 403 B2_API bool b2Body_IsAwake( b2BodyId bodyId ); 404 405 /// Wake a body from sleep. This wakes the entire island the body is touching. 406 /// @warning Putting a body to sleep will put the entire island of bodies touching this body to sleep, 407 /// which can be expensive and possibly unintuitive. 408 B2_API void b2Body_SetAwake( b2BodyId bodyId, bool awake ); 409 410 /// Enable or disable sleeping for this body. If sleeping is disabled the body will wake. 411 B2_API void b2Body_EnableSleep( b2BodyId bodyId, bool enableSleep ); 412 413 /// Returns true if sleeping is enabled for this body 414 B2_API bool b2Body_IsSleepEnabled( b2BodyId bodyId ); 415 416 /// Set the sleep threshold, usually in meters per second 417 B2_API void b2Body_SetSleepThreshold( b2BodyId bodyId, float sleepThreshold ); 418 419 /// Get the sleep threshold, usually in meters per second. 420 B2_API float b2Body_GetSleepThreshold( b2BodyId bodyId ); 421 422 /// Returns true if this body is enabled 423 B2_API bool b2Body_IsEnabled( b2BodyId bodyId ); 424 425 /// Disable a body by removing it completely from the simulation. This is expensive. 426 B2_API void b2Body_Disable( b2BodyId bodyId ); 427 428 /// Enable a body by adding it to the simulation. This is expensive. 429 B2_API void b2Body_Enable( b2BodyId bodyId ); 430 431 /// Set this body to have fixed rotation. This causes the mass to be reset in all cases. 432 B2_API void b2Body_SetFixedRotation( b2BodyId bodyId, bool flag ); 433 434 /// Does this body have fixed rotation? 435 B2_API bool b2Body_IsFixedRotation( b2BodyId bodyId ); 436 437 /// Set this body to be a bullet. A bullet does continuous collision detection 438 /// against dynamic bodies (but not other bullets). 439 B2_API void b2Body_SetBullet( b2BodyId bodyId, bool flag ); 440 441 /// Is this body a bullet? 442 B2_API bool b2Body_IsBullet( b2BodyId bodyId ); 443 444 /// Enable/disable contact events on all shapes. 445 /// @see b2ShapeDef::enableContactEvents 446 /// @warning changing this at runtime may cause mismatched begin/end touch events 447 B2_API void b2Body_EnableContactEvents( b2BodyId bodyId, bool flag ); 448 449 /// Enable/disable hit events on all shapes 450 /// @see b2ShapeDef::enableHitEvents 451 B2_API void b2Body_EnableHitEvents( b2BodyId bodyId, bool flag ); 452 453 /// Get the world that owns this body 454 B2_API b2WorldId b2Body_GetWorld( b2BodyId bodyId ); 455 456 /// Get the number of shapes on this body 457 B2_API int b2Body_GetShapeCount( b2BodyId bodyId ); 458 459 /// Get the shape ids for all shapes on this body, up to the provided capacity. 460 /// @returns the number of shape ids stored in the user array 461 B2_API int b2Body_GetShapes( b2BodyId bodyId, b2ShapeId* shapeArray, int capacity ); 462 463 /// Get the number of joints on this body 464 B2_API int b2Body_GetJointCount( b2BodyId bodyId ); 465 466 /// Get the joint ids for all joints on this body, up to the provided capacity 467 /// @returns the number of joint ids stored in the user array 468 B2_API int b2Body_GetJoints( b2BodyId bodyId, b2JointId* jointArray, int capacity ); 469 470 /// Get the maximum capacity required for retrieving all the touching contacts on a body 471 B2_API int b2Body_GetContactCapacity( b2BodyId bodyId ); 472 473 /// Get the touching contact data for a body. 474 /// @note Box2D uses speculative collision so some contact points may be separated. 475 /// @returns the number of elements filled in the provided array 476 /// @warning do not ignore the return value, it specifies the valid number of elements 477 B2_API int b2Body_GetContactData( b2BodyId bodyId, b2ContactData* contactData, int capacity ); 478 479 /// Get the current world AABB that contains all the attached shapes. Note that this may not encompass the body origin. 480 /// If there are no shapes attached then the returned AABB is empty and centered on the body origin. 481 B2_API b2AABB b2Body_ComputeAABB( b2BodyId bodyId ); 482 483 /** @} */ 484 485 /** 486 * @defgroup shape Shape 487 * Functions to create, destroy, and access. 488 * Shapes bind raw geometry to bodies and hold material properties including friction and restitution. 489 * @{ 490 */ 491 492 /// Create a circle shape and attach it to a body. The shape definition and geometry are fully cloned. 493 /// Contacts are not created until the next time step. 494 /// @return the shape id for accessing the shape 495 B2_API b2ShapeId b2CreateCircleShape( b2BodyId bodyId, const b2ShapeDef* def, const b2Circle* circle ); 496 497 /// Create a line segment shape and attach it to a body. The shape definition and geometry are fully cloned. 498 /// Contacts are not created until the next time step. 499 /// @return the shape id for accessing the shape 500 B2_API b2ShapeId b2CreateSegmentShape( b2BodyId bodyId, const b2ShapeDef* def, const b2Segment* segment ); 501 502 /// Create a capsule shape and attach it to a body. The shape definition and geometry are fully cloned. 503 /// Contacts are not created until the next time step. 504 /// @return the shape id for accessing the shape 505 B2_API b2ShapeId b2CreateCapsuleShape( b2BodyId bodyId, const b2ShapeDef* def, const b2Capsule* capsule ); 506 507 /// Create a polygon shape and attach it to a body. The shape definition and geometry are fully cloned. 508 /// Contacts are not created until the next time step. 509 /// @return the shape id for accessing the shape 510 B2_API b2ShapeId b2CreatePolygonShape( b2BodyId bodyId, const b2ShapeDef* def, const b2Polygon* polygon ); 511 512 /// Destroy a shape. You may defer the body mass update which can improve performance if several shapes on a 513 /// body are destroyed at once. 514 /// @see b2Body_ApplyMassFromShapes 515 B2_API void b2DestroyShape( b2ShapeId shapeId, bool updateBodyMass ); 516 517 /// Shape identifier validation. Provides validation for up to 64K allocations. 518 B2_API bool b2Shape_IsValid( b2ShapeId id ); 519 520 /// Get the type of a shape 521 B2_API b2ShapeType b2Shape_GetType( b2ShapeId shapeId ); 522 523 /// Get the id of the body that a shape is attached to 524 B2_API b2BodyId b2Shape_GetBody( b2ShapeId shapeId ); 525 526 /// Get the world that owns this shape 527 B2_API b2WorldId b2Shape_GetWorld( b2ShapeId shapeId ); 528 529 /// Returns true If the shape is a sensor 530 B2_API bool b2Shape_IsSensor( b2ShapeId shapeId ); 531 532 /// Set the user data for a shape 533 B2_API void b2Shape_SetUserData( b2ShapeId shapeId, void* userData ); 534 535 /// Get the user data for a shape. This is useful when you get a shape id 536 /// from an event or query. 537 B2_API void* b2Shape_GetUserData( b2ShapeId shapeId ); 538 539 /// Set the mass density of a shape, usually in kg/m^2. 540 /// This will optionally update the mass properties on the parent body. 541 /// @see b2ShapeDef::density, b2Body_ApplyMassFromShapes 542 B2_API void b2Shape_SetDensity( b2ShapeId shapeId, float density, bool updateBodyMass ); 543 544 /// Get the density of a shape, usually in kg/m^2 545 B2_API float b2Shape_GetDensity( b2ShapeId shapeId ); 546 547 /// Set the friction on a shape 548 /// @see b2ShapeDef::friction 549 B2_API void b2Shape_SetFriction( b2ShapeId shapeId, float friction ); 550 551 /// Get the friction of a shape 552 B2_API float b2Shape_GetFriction( b2ShapeId shapeId ); 553 554 /// Set the shape restitution (bounciness) 555 /// @see b2ShapeDef::restitution 556 B2_API void b2Shape_SetRestitution( b2ShapeId shapeId, float restitution ); 557 558 /// Get the shape restitution 559 B2_API float b2Shape_GetRestitution( b2ShapeId shapeId ); 560 561 /// Set the shape material identifier 562 /// @see b2ShapeDef::material 563 B2_API void b2Shape_SetMaterial( b2ShapeId shapeId, int material ); 564 565 /// Get the shape material identifier 566 B2_API int b2Shape_GetMaterial( b2ShapeId shapeId ); 567 568 /// Get the shape filter 569 B2_API b2Filter b2Shape_GetFilter( b2ShapeId shapeId ); 570 571 /// Set the current filter. This is almost as expensive as recreating the shape. This may cause 572 /// contacts to be immediately destroyed. However contacts are not created until the next world step. 573 /// Sensor overlap state is also not updated until the next world step. 574 /// @see b2ShapeDef::filter 575 B2_API void b2Shape_SetFilter( b2ShapeId shapeId, b2Filter filter ); 576 577 /// Enable contact events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors. 578 /// @see b2ShapeDef::enableContactEvents 579 /// @warning changing this at run-time may lead to lost begin/end events 580 B2_API void b2Shape_EnableContactEvents( b2ShapeId shapeId, bool flag ); 581 582 /// Returns true if contact events are enabled 583 B2_API bool b2Shape_AreContactEventsEnabled( b2ShapeId shapeId ); 584 585 /// Enable pre-solve contact events for this shape. Only applies to dynamic bodies. These are expensive 586 /// and must be carefully handled due to multithreading. Ignored for sensors. 587 /// @see b2PreSolveFcn 588 B2_API void b2Shape_EnablePreSolveEvents( b2ShapeId shapeId, bool flag ); 589 590 /// Returns true if pre-solve events are enabled 591 B2_API bool b2Shape_ArePreSolveEventsEnabled( b2ShapeId shapeId ); 592 593 /// Enable contact hit events for this shape. Ignored for sensors. 594 /// @see b2WorldDef.hitEventThreshold 595 B2_API void b2Shape_EnableHitEvents( b2ShapeId shapeId, bool flag ); 596 597 /// Returns true if hit events are enabled 598 B2_API bool b2Shape_AreHitEventsEnabled( b2ShapeId shapeId ); 599 600 /// Test a point for overlap with a shape 601 B2_API bool b2Shape_TestPoint( b2ShapeId shapeId, b2Vec2 point ); 602 603 /// Ray cast a shape directly 604 B2_API b2CastOutput b2Shape_RayCast( b2ShapeId shapeId, const b2RayCastInput* input ); 605 606 /// Get a copy of the shape's circle. Asserts the type is correct. 607 B2_API b2Circle b2Shape_GetCircle( b2ShapeId shapeId ); 608 609 /// Get a copy of the shape's line segment. Asserts the type is correct. 610 B2_API b2Segment b2Shape_GetSegment( b2ShapeId shapeId ); 611 612 /// Get a copy of the shape's chain segment. These come from chain shapes. 613 /// Asserts the type is correct. 614 B2_API b2ChainSegment b2Shape_GetChainSegment( b2ShapeId shapeId ); 615 616 /// Get a copy of the shape's capsule. Asserts the type is correct. 617 B2_API b2Capsule b2Shape_GetCapsule( b2ShapeId shapeId ); 618 619 /// Get a copy of the shape's convex polygon. Asserts the type is correct. 620 B2_API b2Polygon b2Shape_GetPolygon( b2ShapeId shapeId ); 621 622 /// Allows you to change a shape to be a circle or update the current circle. 623 /// This does not modify the mass properties. 624 /// @see b2Body_ApplyMassFromShapes 625 B2_API void b2Shape_SetCircle( b2ShapeId shapeId, const b2Circle* circle ); 626 627 /// Allows you to change a shape to be a capsule or update the current capsule. 628 /// This does not modify the mass properties. 629 /// @see b2Body_ApplyMassFromShapes 630 B2_API void b2Shape_SetCapsule( b2ShapeId shapeId, const b2Capsule* capsule ); 631 632 /// Allows you to change a shape to be a segment or update the current segment. 633 B2_API void b2Shape_SetSegment( b2ShapeId shapeId, const b2Segment* segment ); 634 635 /// Allows you to change a shape to be a polygon or update the current polygon. 636 /// This does not modify the mass properties. 637 /// @see b2Body_ApplyMassFromShapes 638 B2_API void b2Shape_SetPolygon( b2ShapeId shapeId, const b2Polygon* polygon ); 639 640 /// Get the parent chain id if the shape type is a chain segment, otherwise 641 /// returns b2_nullChainId. 642 B2_API b2ChainId b2Shape_GetParentChain( b2ShapeId shapeId ); 643 644 /// Get the maximum capacity required for retrieving all the touching contacts on a shape 645 B2_API int b2Shape_GetContactCapacity( b2ShapeId shapeId ); 646 647 /// Get the touching contact data for a shape. The provided shapeId will be either shapeIdA or shapeIdB on the contact data. 648 /// @note Box2D uses speculative collision so some contact points may be separated. 649 /// @returns the number of elements filled in the provided array 650 /// @warning do not ignore the return value, it specifies the valid number of elements 651 B2_API int b2Shape_GetContactData( b2ShapeId shapeId, b2ContactData* contactData, int capacity ); 652 653 /// Get the maximum capacity required for retrieving all the overlapped shapes on a sensor shape. 654 /// This returns 0 if the provided shape is not a sensor. 655 /// @param shapeId the id of a sensor shape 656 /// @returns the required capacity to get all the overlaps in b2Shape_GetSensorOverlaps 657 B2_API int b2Shape_GetSensorCapacity( b2ShapeId shapeId ); 658 659 /// Get the overlapped shapes for a sensor shape. 660 /// @param shapeId the id of a sensor shape 661 /// @param overlaps a user allocated array that is filled with the overlapping shapes 662 /// @param capacity the capacity of overlappedShapes 663 /// @returns the number of elements filled in the provided array 664 /// @warning do not ignore the return value, it specifies the valid number of elements 665 /// @warning overlaps may contain destroyed shapes so use b2Shape_IsValid to confirm each overlap 666 B2_API int b2Shape_GetSensorOverlaps( b2ShapeId shapeId, b2ShapeId* overlaps, int capacity ); 667 668 /// Get the current world AABB 669 B2_API b2AABB b2Shape_GetAABB( b2ShapeId shapeId ); 670 671 /// Get the mass data for a shape 672 B2_API b2MassData b2Shape_GetMassData( b2ShapeId shapeId ); 673 674 /// Get the closest point on a shape to a target point. Target and result are in world space. 675 /// todo need sample 676 B2_API b2Vec2 b2Shape_GetClosestPoint( b2ShapeId shapeId, b2Vec2 target ); 677 678 /// Chain Shape 679 680 /// Create a chain shape 681 /// @see b2ChainDef for details 682 B2_API b2ChainId b2CreateChain( b2BodyId bodyId, const b2ChainDef* def ); 683 684 /// Destroy a chain shape 685 B2_API void b2DestroyChain( b2ChainId chainId ); 686 687 /// Get the world that owns this chain shape 688 B2_API b2WorldId b2Chain_GetWorld( b2ChainId chainId ); 689 690 /// Get the number of segments on this chain 691 B2_API int b2Chain_GetSegmentCount( b2ChainId chainId ); 692 693 /// Fill a user array with chain segment shape ids up to the specified capacity. Returns 694 /// the actual number of segments returned. 695 B2_API int b2Chain_GetSegments( b2ChainId chainId, b2ShapeId* segmentArray, int capacity ); 696 697 /// Set the chain friction 698 /// @see b2ChainDef::friction 699 B2_API void b2Chain_SetFriction( b2ChainId chainId, float friction ); 700 701 /// Get the chain friction 702 B2_API float b2Chain_GetFriction( b2ChainId chainId ); 703 704 /// Set the chain restitution (bounciness) 705 /// @see b2ChainDef::restitution 706 B2_API void b2Chain_SetRestitution( b2ChainId chainId, float restitution ); 707 708 /// Get the chain restitution 709 B2_API float b2Chain_GetRestitution( b2ChainId chainId ); 710 711 /// Set the chain material 712 /// @see b2ChainDef::material 713 B2_API void b2Chain_SetMaterial( b2ChainId chainId, int material ); 714 715 /// Get the chain material 716 B2_API int b2Chain_GetMaterial( b2ChainId chainId ); 717 718 /// Chain identifier validation. Provides validation for up to 64K allocations. 719 B2_API bool b2Chain_IsValid( b2ChainId id ); 720 721 /** @} */ 722 723 /** 724 * @defgroup joint Joint 725 * @brief Joints allow you to connect rigid bodies together while allowing various forms of relative motions. 726 * @{ 727 */ 728 729 /// Destroy a joint 730 B2_API void b2DestroyJoint( b2JointId jointId ); 731 732 /// Joint identifier validation. Provides validation for up to 64K allocations. 733 B2_API bool b2Joint_IsValid( b2JointId id ); 734 735 /// Get the joint type 736 B2_API b2JointType b2Joint_GetType( b2JointId jointId ); 737 738 /// Get body A id on a joint 739 B2_API b2BodyId b2Joint_GetBodyA( b2JointId jointId ); 740 741 /// Get body B id on a joint 742 B2_API b2BodyId b2Joint_GetBodyB( b2JointId jointId ); 743 744 /// Get the world that owns this joint 745 B2_API b2WorldId b2Joint_GetWorld( b2JointId jointId ); 746 747 /// Get the local anchor on bodyA 748 B2_API b2Vec2 b2Joint_GetLocalAnchorA( b2JointId jointId ); 749 750 /// Get the local anchor on bodyB 751 B2_API b2Vec2 b2Joint_GetLocalAnchorB( b2JointId jointId ); 752 753 /// Toggle collision between connected bodies 754 B2_API void b2Joint_SetCollideConnected( b2JointId jointId, bool shouldCollide ); 755 756 /// Is collision allowed between connected bodies? 757 B2_API bool b2Joint_GetCollideConnected( b2JointId jointId ); 758 759 /// Set the user data on a joint 760 B2_API void b2Joint_SetUserData( b2JointId jointId, void* userData ); 761 762 /// Get the user data on a joint 763 B2_API void* b2Joint_GetUserData( b2JointId jointId ); 764 765 /// Wake the bodies connect to this joint 766 B2_API void b2Joint_WakeBodies( b2JointId jointId ); 767 768 /// Get the current constraint force for this joint. Usually in Newtons. 769 B2_API b2Vec2 b2Joint_GetConstraintForce( b2JointId jointId ); 770 771 /// Get the current constraint torque for this joint. Usually in Newton * meters. 772 B2_API float b2Joint_GetConstraintTorque( b2JointId jointId ); 773 774 /** 775 * @defgroup distance_joint Distance Joint 776 * @brief Functions for the distance joint. 777 * @{ 778 */ 779 780 /// Create a distance joint 781 /// @see b2DistanceJointDef for details 782 B2_API b2JointId b2CreateDistanceJoint( b2WorldId worldId, const b2DistanceJointDef* def ); 783 784 /// Set the rest length of a distance joint 785 /// @param jointId The id for a distance joint 786 /// @param length The new distance joint length 787 B2_API void b2DistanceJoint_SetLength( b2JointId jointId, float length ); 788 789 /// Get the rest length of a distance joint 790 B2_API float b2DistanceJoint_GetLength( b2JointId jointId ); 791 792 /// Enable/disable the distance joint spring. When disabled the distance joint is rigid. 793 B2_API void b2DistanceJoint_EnableSpring( b2JointId jointId, bool enableSpring ); 794 795 /// Is the distance joint spring enabled? 796 B2_API bool b2DistanceJoint_IsSpringEnabled( b2JointId jointId ); 797 798 /// Set the spring stiffness in Hertz 799 B2_API void b2DistanceJoint_SetSpringHertz( b2JointId jointId, float hertz ); 800 801 /// Set the spring damping ratio, non-dimensional 802 B2_API void b2DistanceJoint_SetSpringDampingRatio( b2JointId jointId, float dampingRatio ); 803 804 /// Get the spring Hertz 805 B2_API float b2DistanceJoint_GetSpringHertz( b2JointId jointId ); 806 807 /// Get the spring damping ratio 808 B2_API float b2DistanceJoint_GetSpringDampingRatio( b2JointId jointId ); 809 810 /// Enable joint limit. The limit only works if the joint spring is enabled. Otherwise the joint is rigid 811 /// and the limit has no effect. 812 B2_API void b2DistanceJoint_EnableLimit( b2JointId jointId, bool enableLimit ); 813 814 /// Is the distance joint limit enabled? 815 B2_API bool b2DistanceJoint_IsLimitEnabled( b2JointId jointId ); 816 817 /// Set the minimum and maximum length parameters of a distance joint 818 B2_API void b2DistanceJoint_SetLengthRange( b2JointId jointId, float minLength, float maxLength ); 819 820 /// Get the distance joint minimum length 821 B2_API float b2DistanceJoint_GetMinLength( b2JointId jointId ); 822 823 /// Get the distance joint maximum length 824 B2_API float b2DistanceJoint_GetMaxLength( b2JointId jointId ); 825 826 /// Get the current length of a distance joint 827 B2_API float b2DistanceJoint_GetCurrentLength( b2JointId jointId ); 828 829 /// Enable/disable the distance joint motor 830 B2_API void b2DistanceJoint_EnableMotor( b2JointId jointId, bool enableMotor ); 831 832 /// Is the distance joint motor enabled? 833 B2_API bool b2DistanceJoint_IsMotorEnabled( b2JointId jointId ); 834 835 /// Set the distance joint motor speed, usually in meters per second 836 B2_API void b2DistanceJoint_SetMotorSpeed( b2JointId jointId, float motorSpeed ); 837 838 /// Get the distance joint motor speed, usually in meters per second 839 B2_API float b2DistanceJoint_GetMotorSpeed( b2JointId jointId ); 840 841 /// Set the distance joint maximum motor force, usually in newtons 842 B2_API void b2DistanceJoint_SetMaxMotorForce( b2JointId jointId, float force ); 843 844 /// Get the distance joint maximum motor force, usually in newtons 845 B2_API float b2DistanceJoint_GetMaxMotorForce( b2JointId jointId ); 846 847 /// Get the distance joint current motor force, usually in newtons 848 B2_API float b2DistanceJoint_GetMotorForce( b2JointId jointId ); 849 850 /** @} */ 851 852 /** 853 * @defgroup motor_joint Motor Joint 854 * @brief Functions for the motor joint. 855 * 856 * The motor joint is used to drive the relative transform between two bodies. It takes 857 * a relative position and rotation and applies the forces and torques needed to achieve 858 * that relative transform over time. 859 * @{ 860 */ 861 862 /// Create a motor joint 863 /// @see b2MotorJointDef for details 864 B2_API b2JointId b2CreateMotorJoint( b2WorldId worldId, const b2MotorJointDef* def ); 865 866 /// Set the motor joint linear offset target 867 B2_API void b2MotorJoint_SetLinearOffset( b2JointId jointId, b2Vec2 linearOffset ); 868 869 /// Get the motor joint linear offset target 870 B2_API b2Vec2 b2MotorJoint_GetLinearOffset( b2JointId jointId ); 871 872 /// Set the motor joint angular offset target in radians 873 B2_API void b2MotorJoint_SetAngularOffset( b2JointId jointId, float angularOffset ); 874 875 /// Get the motor joint angular offset target in radians 876 B2_API float b2MotorJoint_GetAngularOffset( b2JointId jointId ); 877 878 /// Set the motor joint maximum force, usually in newtons 879 B2_API void b2MotorJoint_SetMaxForce( b2JointId jointId, float maxForce ); 880 881 /// Get the motor joint maximum force, usually in newtons 882 B2_API float b2MotorJoint_GetMaxForce( b2JointId jointId ); 883 884 /// Set the motor joint maximum torque, usually in newton-meters 885 B2_API void b2MotorJoint_SetMaxTorque( b2JointId jointId, float maxTorque ); 886 887 /// Get the motor joint maximum torque, usually in newton-meters 888 B2_API float b2MotorJoint_GetMaxTorque( b2JointId jointId ); 889 890 /// Set the motor joint correction factor, usually in [0, 1] 891 B2_API void b2MotorJoint_SetCorrectionFactor( b2JointId jointId, float correctionFactor ); 892 893 /// Get the motor joint correction factor, usually in [0, 1] 894 B2_API float b2MotorJoint_GetCorrectionFactor( b2JointId jointId ); 895 896 /**@}*/ 897 898 /** 899 * @defgroup mouse_joint Mouse Joint 900 * @brief Functions for the mouse joint. 901 * 902 * The mouse joint is designed for use in the samples application, but you may find it useful in applications where 903 * the user moves a rigid body with a cursor. 904 * @{ 905 */ 906 907 /// Create a mouse joint 908 /// @see b2MouseJointDef for details 909 B2_API b2JointId b2CreateMouseJoint( b2WorldId worldId, const b2MouseJointDef* def ); 910 911 /// Set the mouse joint target 912 B2_API void b2MouseJoint_SetTarget( b2JointId jointId, b2Vec2 target ); 913 914 /// Get the mouse joint target 915 B2_API b2Vec2 b2MouseJoint_GetTarget( b2JointId jointId ); 916 917 /// Set the mouse joint spring stiffness in Hertz 918 B2_API void b2MouseJoint_SetSpringHertz( b2JointId jointId, float hertz ); 919 920 /// Get the mouse joint spring stiffness in Hertz 921 B2_API float b2MouseJoint_GetSpringHertz( b2JointId jointId ); 922 923 /// Set the mouse joint spring damping ratio, non-dimensional 924 B2_API void b2MouseJoint_SetSpringDampingRatio( b2JointId jointId, float dampingRatio ); 925 926 /// Get the mouse joint damping ratio, non-dimensional 927 B2_API float b2MouseJoint_GetSpringDampingRatio( b2JointId jointId ); 928 929 /// Set the mouse joint maximum force, usually in newtons 930 B2_API void b2MouseJoint_SetMaxForce( b2JointId jointId, float maxForce ); 931 932 /// Get the mouse joint maximum force, usually in newtons 933 B2_API float b2MouseJoint_GetMaxForce( b2JointId jointId ); 934 935 /**@}*/ 936 937 /** 938 * @defgroup null_joint Null Joint 939 * @brief Functions for the null joint. 940 * 941 * The null joint is used to disable collision between two bodies. As a side effect of being a joint, it also 942 * keeps the two bodies in the same simulation island. 943 * @{ 944 */ 945 946 /// Create a null joint. 947 /// @see b2NullJointDef for details 948 B2_API b2JointId b2CreateNullJoint( b2WorldId worldId, const b2NullJointDef* def ); 949 950 /**@}*/ 951 952 /** 953 * @defgroup prismatic_joint Prismatic Joint 954 * @brief A prismatic joint allows for translation along a single axis with no rotation. 955 * 956 * The prismatic joint is useful for things like pistons and moving platforms, where you want a body to translate 957 * along an axis and have no rotation. Also called a *slider* joint. 958 * @{ 959 */ 960 961 /// Create a prismatic (slider) joint. 962 /// @see b2PrismaticJointDef for details 963 B2_API b2JointId b2CreatePrismaticJoint( b2WorldId worldId, const b2PrismaticJointDef* def ); 964 965 /// Enable/disable the joint spring. 966 B2_API void b2PrismaticJoint_EnableSpring( b2JointId jointId, bool enableSpring ); 967 968 /// Is the prismatic joint spring enabled or not? 969 B2_API bool b2PrismaticJoint_IsSpringEnabled( b2JointId jointId ); 970 971 /// Set the prismatic joint stiffness in Hertz. 972 /// This should usually be less than a quarter of the simulation rate. For example, if the simulation 973 /// runs at 60Hz then the joint stiffness should be 15Hz or less. 974 B2_API void b2PrismaticJoint_SetSpringHertz( b2JointId jointId, float hertz ); 975 976 /// Get the prismatic joint stiffness in Hertz 977 B2_API float b2PrismaticJoint_GetSpringHertz( b2JointId jointId ); 978 979 /// Set the prismatic joint damping ratio (non-dimensional) 980 B2_API void b2PrismaticJoint_SetSpringDampingRatio( b2JointId jointId, float dampingRatio ); 981 982 /// Get the prismatic spring damping ratio (non-dimensional) 983 B2_API float b2PrismaticJoint_GetSpringDampingRatio( b2JointId jointId ); 984 985 /// Enable/disable a prismatic joint limit 986 B2_API void b2PrismaticJoint_EnableLimit( b2JointId jointId, bool enableLimit ); 987 988 /// Is the prismatic joint limit enabled? 989 B2_API bool b2PrismaticJoint_IsLimitEnabled( b2JointId jointId ); 990 991 /// Get the prismatic joint lower limit 992 B2_API float b2PrismaticJoint_GetLowerLimit( b2JointId jointId ); 993 994 /// Get the prismatic joint upper limit 995 B2_API float b2PrismaticJoint_GetUpperLimit( b2JointId jointId ); 996 997 /// Set the prismatic joint limits 998 B2_API void b2PrismaticJoint_SetLimits( b2JointId jointId, float lower, float upper ); 999 1000 /// Enable/disable a prismatic joint motor 1001 B2_API void b2PrismaticJoint_EnableMotor( b2JointId jointId, bool enableMotor ); 1002 1003 /// Is the prismatic joint motor enabled? 1004 B2_API bool b2PrismaticJoint_IsMotorEnabled( b2JointId jointId ); 1005 1006 /// Set the prismatic joint motor speed, usually in meters per second 1007 B2_API void b2PrismaticJoint_SetMotorSpeed( b2JointId jointId, float motorSpeed ); 1008 1009 /// Get the prismatic joint motor speed, usually in meters per second 1010 B2_API float b2PrismaticJoint_GetMotorSpeed( b2JointId jointId ); 1011 1012 /// Set the prismatic joint maximum motor force, usually in newtons 1013 B2_API void b2PrismaticJoint_SetMaxMotorForce( b2JointId jointId, float force ); 1014 1015 /// Get the prismatic joint maximum motor force, usually in newtons 1016 B2_API float b2PrismaticJoint_GetMaxMotorForce( b2JointId jointId ); 1017 1018 /// Get the prismatic joint current motor force, usually in newtons 1019 B2_API float b2PrismaticJoint_GetMotorForce( b2JointId jointId ); 1020 1021 /// Get the current joint translation, usually in meters. 1022 B2_API float b2PrismaticJoint_GetTranslation( b2JointId jointId ); 1023 1024 /// Get the current joint translation speed, usually in meters per second. 1025 B2_API float b2PrismaticJoint_GetSpeed( b2JointId jointId ); 1026 1027 /** @} */ 1028 1029 /** 1030 * @defgroup revolute_joint Revolute Joint 1031 * @brief A revolute joint allows for relative rotation in the 2D plane with no relative translation. 1032 * 1033 * The revolute joint is probably the most common joint. It can be used for ragdolls and chains. 1034 * Also called a *hinge* or *pin* joint. 1035 * @{ 1036 */ 1037 1038 /// Create a revolute joint 1039 /// @see b2RevoluteJointDef for details 1040 B2_API b2JointId b2CreateRevoluteJoint( b2WorldId worldId, const b2RevoluteJointDef* def ); 1041 1042 /// Enable/disable the revolute joint spring 1043 B2_API void b2RevoluteJoint_EnableSpring( b2JointId jointId, bool enableSpring ); 1044 1045 /// It the revolute angular spring enabled? 1046 B2_API bool b2RevoluteJoint_IsSpringEnabled( b2JointId jointId ); 1047 1048 /// Set the revolute joint spring stiffness in Hertz 1049 B2_API void b2RevoluteJoint_SetSpringHertz( b2JointId jointId, float hertz ); 1050 1051 /// Get the revolute joint spring stiffness in Hertz 1052 B2_API float b2RevoluteJoint_GetSpringHertz( b2JointId jointId ); 1053 1054 /// Set the revolute joint spring damping ratio, non-dimensional 1055 B2_API void b2RevoluteJoint_SetSpringDampingRatio( b2JointId jointId, float dampingRatio ); 1056 1057 /// Get the revolute joint spring damping ratio, non-dimensional 1058 B2_API float b2RevoluteJoint_GetSpringDampingRatio( b2JointId jointId ); 1059 1060 /// Get the revolute joint current angle in radians relative to the reference angle 1061 /// @see b2RevoluteJointDef::referenceAngle 1062 B2_API float b2RevoluteJoint_GetAngle( b2JointId jointId ); 1063 1064 /// Enable/disable the revolute joint limit 1065 B2_API void b2RevoluteJoint_EnableLimit( b2JointId jointId, bool enableLimit ); 1066 1067 /// Is the revolute joint limit enabled? 1068 B2_API bool b2RevoluteJoint_IsLimitEnabled( b2JointId jointId ); 1069 1070 /// Get the revolute joint lower limit in radians 1071 B2_API float b2RevoluteJoint_GetLowerLimit( b2JointId jointId ); 1072 1073 /// Get the revolute joint upper limit in radians 1074 B2_API float b2RevoluteJoint_GetUpperLimit( b2JointId jointId ); 1075 1076 /// Set the revolute joint limits in radians 1077 B2_API void b2RevoluteJoint_SetLimits( b2JointId jointId, float lower, float upper ); 1078 1079 /// Enable/disable a revolute joint motor 1080 B2_API void b2RevoluteJoint_EnableMotor( b2JointId jointId, bool enableMotor ); 1081 1082 /// Is the revolute joint motor enabled? 1083 B2_API bool b2RevoluteJoint_IsMotorEnabled( b2JointId jointId ); 1084 1085 /// Set the revolute joint motor speed in radians per second 1086 B2_API void b2RevoluteJoint_SetMotorSpeed( b2JointId jointId, float motorSpeed ); 1087 1088 /// Get the revolute joint motor speed in radians per second 1089 B2_API float b2RevoluteJoint_GetMotorSpeed( b2JointId jointId ); 1090 1091 /// Get the revolute joint current motor torque, usually in newton-meters 1092 B2_API float b2RevoluteJoint_GetMotorTorque( b2JointId jointId ); 1093 1094 /// Set the revolute joint maximum motor torque, usually in newton-meters 1095 B2_API void b2RevoluteJoint_SetMaxMotorTorque( b2JointId jointId, float torque ); 1096 1097 /// Get the revolute joint maximum motor torque, usually in newton-meters 1098 B2_API float b2RevoluteJoint_GetMaxMotorTorque( b2JointId jointId ); 1099 1100 /**@}*/ 1101 1102 /** 1103 * @defgroup weld_joint Weld Joint 1104 * @brief A weld joint fully constrains the relative transform between two bodies while allowing for springiness 1105 * 1106 * A weld joint constrains the relative rotation and translation between two bodies. Both rotation and translation 1107 * can have damped springs. 1108 * 1109 * @note The accuracy of weld joint is limited by the accuracy of the solver. Long chains of weld joints may flex. 1110 * @{ 1111 */ 1112 1113 /// Create a weld joint 1114 /// @see b2WeldJointDef for details 1115 B2_API b2JointId b2CreateWeldJoint( b2WorldId worldId, const b2WeldJointDef* def ); 1116 1117 /// Get the weld joint reference angle in radians 1118 B2_API float b2WeldJoint_GetReferenceAngle( b2JointId jointId ); 1119 1120 /// Set the weld joint reference angle in radians, must be in [-pi,pi]. 1121 B2_API void b2WeldJoint_SetReferenceAngle( b2JointId jointId, float angleInRadians ); 1122 1123 /// Set the weld joint linear stiffness in Hertz. 0 is rigid. 1124 B2_API void b2WeldJoint_SetLinearHertz( b2JointId jointId, float hertz ); 1125 1126 /// Get the weld joint linear stiffness in Hertz 1127 B2_API float b2WeldJoint_GetLinearHertz( b2JointId jointId ); 1128 1129 /// Set the weld joint linear damping ratio (non-dimensional) 1130 B2_API void b2WeldJoint_SetLinearDampingRatio( b2JointId jointId, float dampingRatio ); 1131 1132 /// Get the weld joint linear damping ratio (non-dimensional) 1133 B2_API float b2WeldJoint_GetLinearDampingRatio( b2JointId jointId ); 1134 1135 /// Set the weld joint angular stiffness in Hertz. 0 is rigid. 1136 B2_API void b2WeldJoint_SetAngularHertz( b2JointId jointId, float hertz ); 1137 1138 /// Get the weld joint angular stiffness in Hertz 1139 B2_API float b2WeldJoint_GetAngularHertz( b2JointId jointId ); 1140 1141 /// Set weld joint angular damping ratio, non-dimensional 1142 B2_API void b2WeldJoint_SetAngularDampingRatio( b2JointId jointId, float dampingRatio ); 1143 1144 /// Get the weld joint angular damping ratio, non-dimensional 1145 B2_API float b2WeldJoint_GetAngularDampingRatio( b2JointId jointId ); 1146 1147 /** @} */ 1148 1149 /** 1150 * @defgroup wheel_joint Wheel Joint 1151 * The wheel joint can be used to simulate wheels on vehicles. 1152 * 1153 * The wheel joint restricts body B to move along a local axis in body A. Body B is free to 1154 * rotate. Supports a linear spring, linear limits, and a rotational motor. 1155 * 1156 * @{ 1157 */ 1158 1159 /// Create a wheel joint 1160 /// @see b2WheelJointDef for details 1161 B2_API b2JointId b2CreateWheelJoint( b2WorldId worldId, const b2WheelJointDef* def ); 1162 1163 /// Enable/disable the wheel joint spring 1164 B2_API void b2WheelJoint_EnableSpring( b2JointId jointId, bool enableSpring ); 1165 1166 /// Is the wheel joint spring enabled? 1167 B2_API bool b2WheelJoint_IsSpringEnabled( b2JointId jointId ); 1168 1169 /// Set the wheel joint stiffness in Hertz 1170 B2_API void b2WheelJoint_SetSpringHertz( b2JointId jointId, float hertz ); 1171 1172 /// Get the wheel joint stiffness in Hertz 1173 B2_API float b2WheelJoint_GetSpringHertz( b2JointId jointId ); 1174 1175 /// Set the wheel joint damping ratio, non-dimensional 1176 B2_API void b2WheelJoint_SetSpringDampingRatio( b2JointId jointId, float dampingRatio ); 1177 1178 /// Get the wheel joint damping ratio, non-dimensional 1179 B2_API float b2WheelJoint_GetSpringDampingRatio( b2JointId jointId ); 1180 1181 /// Enable/disable the wheel joint limit 1182 B2_API void b2WheelJoint_EnableLimit( b2JointId jointId, bool enableLimit ); 1183 1184 /// Is the wheel joint limit enabled? 1185 B2_API bool b2WheelJoint_IsLimitEnabled( b2JointId jointId ); 1186 1187 /// Get the wheel joint lower limit 1188 B2_API float b2WheelJoint_GetLowerLimit( b2JointId jointId ); 1189 1190 /// Get the wheel joint upper limit 1191 B2_API float b2WheelJoint_GetUpperLimit( b2JointId jointId ); 1192 1193 /// Set the wheel joint limits 1194 B2_API void b2WheelJoint_SetLimits( b2JointId jointId, float lower, float upper ); 1195 1196 /// Enable/disable the wheel joint motor 1197 B2_API void b2WheelJoint_EnableMotor( b2JointId jointId, bool enableMotor ); 1198 1199 /// Is the wheel joint motor enabled? 1200 B2_API bool b2WheelJoint_IsMotorEnabled( b2JointId jointId ); 1201 1202 /// Set the wheel joint motor speed in radians per second 1203 B2_API void b2WheelJoint_SetMotorSpeed( b2JointId jointId, float motorSpeed ); 1204 1205 /// Get the wheel joint motor speed in radians per second 1206 B2_API float b2WheelJoint_GetMotorSpeed( b2JointId jointId ); 1207 1208 /// Set the wheel joint maximum motor torque, usually in newton-meters 1209 B2_API void b2WheelJoint_SetMaxMotorTorque( b2JointId jointId, float torque ); 1210 1211 /// Get the wheel joint maximum motor torque, usually in newton-meters 1212 B2_API float b2WheelJoint_GetMaxMotorTorque( b2JointId jointId ); 1213 1214 /// Get the wheel joint current motor torque, usually in newton-meters 1215 B2_API float b2WheelJoint_GetMotorTorque( b2JointId jointId ); 1216 1217 /**@}*/ 1218 1219 /**@}*/