NewtonGetBuoyancyPlane

From Newton Wiki
Jump to: navigation, search

NewtonGetBuoyancyPlane

typedef int (*NewtonGetBuoyancyPlane) (const int collisionID, void *context, const dFloat* globalSpaceMatrix, dFloat* globalSpacePlane);

Usage

This callback is called when the user calls the NewtonBodyAddBuoyancyForce command to add buoyancy to a Rigid Body.

Parameters

  • const int collisionID - the id of the collision primitive for which the callback is being called.
  • void *context - this is just a pointer to whatever you passed into the "context" parameter of the NewtonBodyAddBuoyancyForce command. you can use this to pass the user data of the Rigid Body, etc. it's like a mini "UserData" just for this function.
  • const dFloat* globalSpaceMatrix - this is the matrix of the primitive (collision shape) having buoyancy applied to it.
  • dFloat* globalSpacePlane - this is the 4-value vector that represents the plane equation for the buoyancy surface. you will need to fill this with meaningful data inside the function.

Return

  • Return 1 to apply buoyancy or 0 for no buyoancy.

Remarks

  • This is not a library function, but a callback event.
  • For compound collision bodies, this function is called back for each primitive contained in the compound collision, with globalSpaceMatrix set to it's transform.

Examples

Simple example use, assuming a flat buoyancy plane, surface +3 units from the origin in the Y direction:

int _cdecl SimpleGetBuoyancy(const int collisionID, void* context, const float* globalSpaceMatrix, float* globalSpacePlane )
{
   // the normal for the plane is just a unit vector.
   globalSpacePlane[0] = 0.0f;
   globalSpacePlane[1] = 1.0f;
   globalSpacePlane[2] = 0.0f;

   // the distance along this normal, to the origin.
   globalSpacePlane[3] = -3.0f
   // Apply force
   return 1;
}

A more in-depth explanation of the bouyancy equation, from the Newton forums (user Julio Jerez): The plane equation is in global space.

The formula is: N dot X + d = 0

That is the dot product of any point on the surface of the plane plus some value should be equal zero.

The way d is calculated is by taking a point that we now is in the plane running it though the formulae. In you example this will be:

N = Vector (0, 1, 0) X = Point at (0, 4, 0)

Then: N dot X + d = 0 0 * 0 + 1 * 4 + 0 * 0 + d = 0 d = -4

the plane equation is ;

0 * x + 1 * y + 0 * z - 4 = 0 y – 4 = 0

Newton wants the coefficient of the plane equation; in this case you pass (0, 1, 0, -4) to the call back

See also

Buoyancy Notes on buoyancy