-- | Description: Low-level Haskell bindings to Chipmunk2D physics library
-- Chiphunk is a __low-level__ Haskell bindings for the <https://chipmunk-physics.net/ Chipmunk2D physics engine>.
-- It includes most (almost all) of the functions mentioned in the main documentation for Chipmunk2D,
-- except for some (relatively) exotic ones, which may be added later per request.
module Chiphunk.Low
  ( -- * Disclaymer

    -- | This bindings are so low-level so that they even require you to free the memory the Chipmunk2D has allocated
    -- for your objects. Module with more high-level api can be built around this low-level bingings at some point,
    -- in the meantime, however, you're advised to provide wrapper layer for your games so that you do not have to
    -- keep track of such things in the core of your game's logic.
    --
    -- See below for an adoptation of the original Chipmunk documentation available
    -- <https://chipmunk-physics.net/release/ChipmunkLatest-Docs/ here>. I've skipped some sections not related
    -- to the bindings, like the reason author chose C language in the first place and limitations of the C api.
    -- Obviously, it's thanks to that choice that I was able to write bindings around the library in Haskell.
    --
    -- __Howling Moon Software is not affiliated with this bindings.__
    -- __In all of the following \"I\" refers to the original documentation author for Chipmunk2D.__

    -- * Chipmunk2D 7.0.2

    -- | Chipmunk2D is a 2D rigid body physics library distributed under the MIT license.
    -- It is blazingly fast, portable, numerically stable, and easy to use.
    -- For this reason it has been used in hundreds of games across just about every system you can name.
    -- This includes top quality titles such as Night Sky for the Wii and many #1 sellers on the iPhone App Store!
    -- I’ve put thousands of hours of work over many years to make Chipmunk2D what it is today.
    -- If you find Chipmunk2D has saved you a lot of time, please consider
    -- <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6666552 donating>.
    -- You’ll make an indie game developer very happy!

    -- | First of all, I would like to give a Erin Catto a big thank you, as Chipmunk2D’s impulse solver
    -- was directly inspired by his example code way back in 2006.
    -- (Now a full fledged physics engine all its own: <http://www.box2d.org/ Box2D.org>).
    -- His contact persistence idea allows for stable stacks of objects with very few iterations of the solver.
    -- My previous solver produced mushy piles of objects or required a large amount of CPU to operate stably.

    -- ** Support

    -- | The best way to get support is to visit the <http://www.slembcke.net/forums/viewforum.php?f=1 Chipmunk Forums>.
    -- There are plenty of people around using Chipmunk on the just about every platform
    -- I’ve ever heard of. If you are working on a commercial project, Howling Moon Software
    -- (my company) is <http://howlingmoonsoftware.com/contracting.php available for contracting>.
    -- We can help with implementing custom Chipmunk behaviors,
    -- as well as priority bug fixes and performance tuning.

    -- ** Contact

    -- | If you find any bugs in Chipmunk, errors or broken links in this document,
    -- or have a question or comment about Chipmunk you can contact me at
    -- slembcke(at)gmail(dot)com. (email or GTalk)

    -- ** License

    -- | Chipmunk is licensed under the MIT license.
    --
    -- @
    -- Copyright (c) 2007-2015 Scott Lembcke and Howling Moon Software
    --
    -- Permission is hereby granted, free of charge, to any person obtaining a copy
    -- of this software and associated documentation files (the "Software"), to deal
    -- in the Software without restriction, including without limitation the rights
    -- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    -- copies of the Software, and to permit persons to whom the Software is
    -- furnished to do so, subject to the following conditions:
    --
    -- The above copyright notice and this permission notice shall be included in
    -- all copies or substantial portions of the Software.
    --
    -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    -- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    -- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    -- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    -- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    -- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    -- SOFTWARE.
    -- @
    --
    -- This means that you do not have to buy a license or pay to use Chipmunk in commercial projects. (Though we really appreciate donations)

    -- ** Links

    -- |
    -- * <http://chipmunk2d.net/forum Chipmunk Forums> – The official forum Chipmunk2D forum.
    --
    -- * <http://howlingmoonsoftware.com/ Howling Moon Software> – The software company I co-founded.
    -- (We are available for contract work!)
    --
    -- * <http://chipmunk2d.net/games.php Games> – A small list of games we know that use Chipmunk.

    -- * Hello Chipmunk (World)

    -- | Hello world Chipmunk style. Create a simple simulation where a ball falls onto a static line segment,
    -- then rolls off. Print out the coordinates of the ball.
    --
    -- @
    -- main :: IO ()
    -- main = do
    --   let gravity = 'Vect' 0 (-100)
    --
    --   -- Create an empty space.
    --   space <- 'spaceNew'
    --   'spaceGravity' space $= gravity
    --
    --   -- Add a static line segment shape for the ground.
    --   -- We'll make it slightly tilted so the ball will roll off.
    --   -- We attach it to a static body to tell Chipmunk it shouldn't be movable.
    --   static <- get $ 'spaceStaticBody' space
    --   ground <- 'segmentShapeNew' static (Vect (-20) 5) (Vect 20 (-5)) 0
    --   'shapeFriction' ground $= 1
    --   'spaceAddShape' space ground
    --
    --   -- Now let's make a ball that falls onto the line and rolls off.
    --   -- First we need to make a cpBody to hold the physical properties of the object.
    --   -- These include the mass, position, velocity, angle, etc. of the object.
    --   -- Then we attach collision shapes to the 'Body' to give it a size and shape.
    --
    --   let radius = 5
    --   let mass = 1
    --
    --   -- The moment of inertia is like mass for rotation
    --   -- Use the momentFor* functions to help you approximate it.
    --   let moment = 'momentForCircle' mass 0 radius (Vect 0 0)
    --
    --   -- The spaceAdd* functions return the thing that you are adding.
    --   ballBody <- 'bodyNew' mass moment
    --   'spaceAddBody' space ballBody
    --   'bodyPosition' ballBody $= Vect 0 15
    --
    --   -- Now we create the collision shape for the ball.
    --   -- You can create multiple collision shapes that point to the same body.
    --   -- They will all be attached to the body and move around to follow it.
    --   ballShape <- 'circleShapeNew' ballBody radius (Vect 0 0)
    --   'spaceAddShape' space ballShape
    --   'shapeFriction' ballShape $= 0.7
    --
    --   -- Now that it's all set up, we simulate all the objects in the space by
    --   -- stepping forward through time in small increments called steps.
    --   -- It is *highly* recommended to use a fixed size time step.
    --   let timeStep = 1/60
    --   runFor 2 timeStep $ \time -> do
    --     pos <- get $ 'bodyPosition' ballBody
    --     vel <- get $ 'bodyVelocity' ballBody
    --     printf "Time is %4.2f. ballBody is at (%6.2f, %6.2f), it's velocity is (%6.2f, %6.2f).\n"
    --            time (vX pos) (vY pos) (vX vel) (vY vel)
    --
    --     'spaceStep' space timeStep
    --
    --   'shapeFree' ballShape
    --   'bodyFree' ballBody
    --   'shapeFree' ground
    --   'spaceFree' space
    --   where
    --     runFor time step inner = go time
    --       where
    --         go time'
    --           | time' <= 0 = pure ()
    --           | otherwise  = inner (time - time') *> go (time' - step)
    -- @

    -- * Chipmunk2D Basics

    -- ** Overview

    -- | There are 4 basic object types you will use in Chipmunk.

    -- |
    -- * __Rigid Bodies__ ('Body'): A rigid body holds the physical properties of an object.
    -- (mass, position, rotation, velocity, etc.) It does not have a shape until you attach one or more collision shapes
    -- to it. If you’ve done physics with particles before, rigid bodies differ in that they are able to rotate.
    -- Rigid bodies generally tend to have a 1:1 correlation to sprites in a game.
    -- You should structure your game so that you use the position and rotation of the rigid body
    -- for drawing your sprite.
    --
    -- * __Collision Shapes__ ('Shape'): By attaching shapes to bodies, you can define the a body’s shape.
    -- You can attach as many shapes to a single body as you need to in order to define a complex shape.
    -- Shapes contain the surface properties of an object such as how much friction or elasticity it has.
    --
    -- * __Constraints/Joints__ ('Constraint'): Constraints and joints describe how bodies are attached to each other.
    --
    -- * __Spaces__ ('Space'): Spaces are containers for simulating objects in Chipmunk.
    -- You add bodies, shapes and joints to a space and then update the space as a whole.
    -- They control how all the rigid bodies, shapes, and constraints interact together.
    --
    -- There is often confusion between rigid bodies and their collision shapes in Chipmunk
    -- and how they relate to sprites. A sprite would be a visual representation of an object,
    -- while a collision shape is an invisible property that defines how objects should collide.
    -- Both the sprite’s and the collision shape’s position and rotation are controlled by the motion of a rigid body.
    -- Generally you want to create a game object type that ties these things all together.

    -- ** Memory Management the Chipmunk way

    -- | For most of the structures you will use, Chipmunk uses a more or less standard and straightforward set
    -- of memory management functions. Take the 'Space' struct for example:
    --
    -- * 'spaceNew' — Allocates and initializes a 'Space' struct.
    --
    -- * 'spaceFree' — Destroys and frees the 'Space' struct.
    --
    -- You are responsible for freeing any structs that you allocate. Chipmunk does not do reference counting or garbage collection. If you call a new function, you must call the matching free function or you will leak memory.

    -- ** Math the Chipmunk way

    -- | First of all, Chipmunk uses double precision floating point numbers throughout its calculations by default.
    -- This is likely to be faster on most modern desktop processors,
    -- and means you don’t have to worry as much about floating point accuracy.
    --
    -- However, there are a few unique functions you will probably find very useful:
    fClamp
  , fLerp
  , fLerpConst

    -- * Chipmunk Vectors

    -- ** Struct Definition, Constants and Constructors
  , Vect (..)
  , vZero
  , cpv

  -- ** Operations

  -- | (__Note for bindings__: Most of these are Chipmunk2D-style aliases for 'Vect' typeclasses methods:
  -- 'Eq', 'Data.VectorSpace.AdditiveGroup', 'Data.VectorSpace.VectorSpace', 'Data.VectorSpace.InnerSpace',
  -- 'Data.Cross.HasCross2')
  , vEql
  , vAdd
  , vSub
  , vNeg
  , vMult
  , vDot
  , vCross
  , vPerp
  , vRPerp
  , vProject
  , vRotate
  , vUnRotate
  , vLength
  , vLengthSq
  , vLerp
  , vLerpConst
  , vSLerp
  , vSLerpConst
  , vNormalize
  , vClamp
  , vDist
  , vDistSq
  , vNear
  , vForAngle
  , vToAngle

    -- * Chipmunk Axis Aligned Bounding Boxes

    -- ** Struct Definition and Constructors

  , BB (..)
  , bbNew
  , bbNewForExtents
  , bbNewForCircle

    -- ** Operations

  , bbIntersects
  , bbContainsBB
  , bbContainsVect
  , bbMerge
  , bbExpand
  , bbCenter
  , bbArea
  , bbMergedArea
  , bbSegmentQuery
  , bbIntersectsSegment
  , bbClampVect
  , bbWrapVect

    -- * Chipmunk Rigid Bodies
  , Body

    -- ** Dynamic, Kinematic, and Static Bodies
  , BodyType (..)

    -- ** Movement, Teleportation, and Velocity

    -- | A graphics engine only needs to know the position of an object for each frame that its drawn.
    -- For a physics engine, this isn’t enough information to calculate a collision response.
    -- When you set the position of a body, you are effectively asking it to teleport itself.
    -- This means that it will instantly move to its new position instead of moving through space and time
    -- like a normal object. If you teleport an object so that it overlaps another one,
    -- the best the physics engine can do is to attempt to push the objects apart again
    -- since there is no information about their movement. This generally results in very mushy looking collisions.
    -- So instead of setting the position of an object, it’s better to set its velocity and allow the physics engine
    -- to update the position. That way it can resolve any resulting colisions natuarally since it knows
    -- how the objects were moving. This is why kinematic bodies work the way they do.
    -- You set the velocity, and the physics updates their position so the two are never out of sync.
    --
    -- For dynamic bodies, setting the velocity explicitly every frame can cause problems.
    -- For example, a problem occurs when a light dynamic body (like a person) is pressed against a heavy dynamic body
    -- (like a car), and you set velocity of the small object so that it’s pushing it into the big body.
    -- To the physics engine, the change in velocity is the same as applying a large impulse
    -- (a very short, very large force). Even if the velocity is low, the large force can allow the small body
    -- to push the big body, even when it normally wouldn’t be able to. For example, a person walking into a car
    -- can overpower the car’s friction and cause it to creep along the ground slowly.
    -- Additionally, when you set the velocity of an object that is already in contact,
    -- it can cause the two objects to overlap by a small amount. The easiest way to avoid both of these problems
    -- is to make smaller changes to the body’s velocity, accelerating it over a fraction of a second
    -- instead of a single frame. An even better solution, which is covered more thoroughly later,
    -- is to use constraints to move the object.

    -- ** Memory Management Functions

    -- | Standard set of Chipmunk memory management functions.
  , bodyNew
  , bodyNewKinematic
  , bodyNewStatic
  , bodyFree

    -- ** Creating Dynamic Bodies

    -- | There are two ways to set up a dynamic body. The easiest option is to create a body
    -- with a mass and moment of 0, and set the mass or density of each collision shape added to the body.
    -- Chipmunk will automatically calculate the mass, moment of inertia, and center of gravity for you.
    -- This is probably preferred in most cases.
    --
    -- The other option is to set the mass of the body when it’s created, and leave the mass of the shapes
    -- added to it as 0.0. This approach is more flexible, but is not as easy to use.
    -- __Don’t__ set the mass of both the body and the shapes. If you do so,
    -- it will recalculate and overwite your custom mass value when the shapes are added to the body.

    -- ** Properties

    -- | Chipmunk provides getter/setter functions for a number of properties on rigid bodies.
    -- Setting most properties automatically wakes the rigid bodies up if they were sleeping.

  , bodyType
  , bodyMass
  , bodyMoment
  , bodyPosition
  , bodyCenterOfGravity
  , bodyVelocity
  , bodyForce
  , bodyAngle
  , bodyAngularVelocity
  , bodyTorque
  , bodyRotation
  , bodySpace
  , bodyUserData

    -- ** Moment of Inertia and Area Helper Functions

    -- | Use the following functions to approximate the moment of inertia for your body,
    -- adding the results together if you want to use more than one.
  , momentForCircle
  , momentForSegment
  , momentForPoly
  , momentForBox

    -- | Use the following functions to get the area for common Chipmunk shapes if you want to approximate masses
    -- or density or whatnot.
  , areaForCircle
  , areaForSegment
  , areaForPoly

    -- ** Coordinate Conversion Functions

    -- | Many things are defined in coordinates local to a body meaning that the (0,0) is at the center of gravity
    -- of the body and the axis rotate along with the body.
  , bodyLocalToWorld
  , bodyWorldToLocal

    -- ** Velocity Conversion Functions

    -- | It’s often useful to know the absolute velocity of a point on the surface of a body
    -- since the angular velocity affects everything except the center of gravity.
  , bodyVelocityAtWorldPoint

    -- ** Applying Forces and Torques

    -- | People are sometimes confused by the difference between a force and an impulse.
    -- An impulse is a very large force applied over a very short period of time.
    -- Some examples are a ball hitting a wall or cannon firing. Chipmunk treats impulses as if they occur
    -- instantaneously by adding directly to the velocity of an object.
    -- Both impulses and forces are affected the mass of an object.
    -- Doubling the mass of the object will halve the effect.
  , bodyApplyForceAtWorldPoint
  , bodyApplyForceAtLocalPoint
  , bodyApplyImpulseAtWorldPoint
  , bodyApplyImpulseAtLocalPoint

    -- ** Sleeping Functions

    -- | Chipmunk supports a sleeping feature which improves performance by not simulating groups of objects
    -- that aren’t moving. Read more about it in the 'Space' section.
  , bodyIsSleeping
  , bodyActivate
  , bodySleep
  , bodyActivateStatic
  , bodySleepWithGroup

    -- ** Iterators
  , BodyShapeIteratorFunc
  , bodyEachShape
  , BodyConstraintIteratorFunc
  , bodyEachConstraint
  , BodyArbiterIteratorFunc
  , bodyEachArbiter

    -- * Chipmunk Collision Shapes

  , Shape

    -- ** Properties

    -- | Chipmunk provides getter/setter functions for a number of properties on collision shapes.
    -- Setting most properties will automatically wake the attached rigid body, if it’s sleeping.

  , shapeBody
  , shapeBB
  , shapeSensor
  , shapeElasticity
  , shapeFriction
  , shapeSurfaceVelocity
  , shapeCollisionType
  , ShapeFilter (..)
  , shapeFilter
  , shapeSpace
  , shapeUserData

    -- ** Fast Collision Filtering using ShapeFilter

    -- | Chipmunk has two primary means of ignoring collisions: groups and category masks.
    --
    -- __Groups__ are used to ignore collisions between parts on a complex object.
    -- A ragdoll is a good example. When jointing an arm onto the torso, you’ll want them to allow them to overlap.
    -- Groups allow you to do exactly that. Shapes that have the same group don’t generate collisions.
    -- So by placing all of the shapes in a ragdoll in the same group, you’ll prevent it from colliding
    -- against other parts of itself.
    -- __Category__ masks allow you to mark which categories an object belongs to
    -- and which categories it collidies with.
    --
    -- For example, a game has four collision categories: player (0), enemy (1), player bullet (2),
    -- and enemy bullet (3). Neither players nor enemies should not collide with their own bullets,
    -- and bullets should not collide with other bullets.
    -- However, players collide with enemy bullets, and enemies collide with player bullets.
    --
    -- +-----------------+-----------------+---------------+
    -- | Object          | Object Category | Category Mask |
    -- +=================+=================+===============+
    -- | \"Player\"      | 1               | 4, 5          |
    -- +-----------------+-----------------+---------------+
    -- | \"Enemy\"       | 2               | 2, 3, 5       |
    -- +-----------------+-----------------+---------------+
    -- | "Player Bullet" | 3               | 1, 5          |
    -- +-----------------+-----------------+---------------+
    -- | "Enemy Bullet"  | 4               | 2, 5          |
    -- +-----------------+-----------------+---------------+
    -- | \"Walls\"       | 5               | 1, 2, 3, 4    |
    -- +-----------------+-----------------+---------------+
    --
    -- Note that everything in this example collides with walls. Additionally, the enemies collide with eachother.
    --
    -- By default, objects exist in every category and collide with every category.
    --
    -- Objects can fall into multiple categories. For instance, you might have a category for a red team,
    -- and have a red player bullet. In the above example, each object only has one category.
    --
    -- There is one last way of filtering collisions using collision handlers. See the section on callbacks
    -- for more information. Collision handlers can be more flexible, but can be slower.
    -- Fast collision filtering rejects collisions before running the expensive collision detection code,
    -- so using groups or category masks is preferred.

    -- ** Memory Management Functions
  , shapeFree

    -- ** Misc functions
  , shapeCacheBB
  , shapeUpdate

    -- ** Working With Circle Shapes
  , circleShapeNew

    -- ** Working With Segment Shapes
  , segmentShapeNew
  , segmentShapeNeighbors

    -- ** Working With Polygon Shapes
  , polyShapeNew
  , polyShapeNewRaw

    -- *** Boxes

    -- | Because boxes are so common in physics games, Chipmunk provides shortcuts to create box shaped polygons.
    -- The boxes will always be centered at the center of gravity of the body you are attaching them to.
    -- Adding a small radius will bevel the corners and can significantly reduce problems
    -- where the box gets stuck on seams in your geometry. If you want to create an off-center box,
    -- you will need to use 'polyShapeNew'.
  , boxShapeNew
  , boxShapeNew2

    -- *** Poly Shape Helper Functions
  , centroidForPoly

    -- *** Convex Hull Helper Functions
  , convexHull

    -- ** Modifying 'Shape's

    -- | The short answer is that you can’t because the changes would be only picked up as a change to the position
    -- of the shape’s surface, but not its velocity.

    -- ** Notes

    -- |
    -- * You can attach multiple collision shapes to a rigid body. This should allow you to create almost any shape
    -- you could possibly need.
    --
    -- * Shapes attached to the same rigid body will never generate collisions. You don’t have to worry
    -- about overlap when attaching multiple shapes to a rigid body.
    --
    -- * Make sure you add both the body and its collision shapes to a space.

    -- * Chipmunk Spaces
  , Space

    -- ** What Are Iterations, and Why Should I Care?

    -- | Chipmunk uses an iterative solver to figure out the forces between objects in the space.
    -- What this means is that it builds a big list of all of the collisions, joints, and other constraints
    -- between the bodies and makes several passes over the list considering each one individually.
    -- The number of passes it makes is the iteration count, and each iteration makes the solution more accurate.
    -- If you use too many iterations, the physics should look nice and solid, but may use up too much CPU time.
    -- If you use too few iterations, the simulation may seem mushy or bouncy when the objects should be solid.
    -- Setting the number of iterations lets you balance between CPU usage and the accuracy of the physics.
    -- Chipmunk’s default of 10 iterations is sufficient for most simple games.

    -- ** Sleeping

    -- | Spaces can disable entire groups of objects that have stopped moving to save CPU time and battery life.
    -- In order to use this feature you must do two things. You must enable sleeping explicitly
    -- by choosing a time threshold value with 'spaceSetSleepTimeThreshold'. This threshold is the amount of time
    -- something must be idle before it falls asleep. 'spaceSetIdleSpeedThreshold' defines what is considered idle.
    -- If you do not set idle speed threshold explicitly, a value will be chosen automatically
    -- based on the current amount of gravity. Be mindful that objects cannot fall asleep if they are touching
    -- or jointed to a kinematic body.

    -- ** Properties

  , spaceIterations
  , spaceGravity
  , spaceDamping
  , spaceIdleSpeedThreshold
  , spaceSleepTimeThreshold
  , spaceCollisionSlop
  , spaceCollisionBias
  , spaceCollisionPersistence
  , spaceCurrentTimeStep
  , spaceIsLocked
  , spaceUserData
  , spaceStaticBody

    -- ** Memory Management Functions

    -- | More standard Chipmunk memory functions.
  , spaceNew
  , spaceFree

    -- ** Operations

    -- | These functions add and remove shapes, bodies and constraints from space. The add/remove functions
    -- cannot be called from within a callback other than a 'postStep' callback (which is different than a 'postSolve'
    -- callback!). Attempting to add or remove objects from the space while 'spaceStep' is still executing
    -- will throw an assertion. See the callbacks section for more information. Be careful not to free bodies
    -- before removing shapes and constraints attached to them or you will cause crashes..
    -- The contains functions allow you to check if an object has been added to the space or not.
  , spaceAddShape
  , spaceAddBody
  , spaceAddConstraint
  , spaceRemoveShape
  , spaceRemoveBody
  , spaceRemoveConstraint
  , spaceContainsShape
  , spaceContainsBody
  , spaceContainsConstraint

    -- ** Spatial Indexing

    -- | Occasionally, you might want to update the collision detection data for a shape.
    -- If you move a static shape or a static body you must do this to let Chipmunk know
    -- it needs to have its collision detection data updated. You may also want to manually update the collision data
    -- for normal shapes if you move them and still want to perform queries against them
    -- before the next call to 'spaceStep'.
  , spaceReindexShape
  , spaceReindexShapesForBody
  , spaceReindexStatic

    -- ** Iterators
  , SpaceBodyIteratorFunc
  , spaceEachBody
  , SpaceShapeIteratorFunc
  , spaceEachShape
  , SpaceConstraintIteratorFunc
  , spaceEachConstraint

    -- ** Simulating the Space
  , spaceStep

    -- * Notes

    -- |
    -- * When removing objects from the space, make sure you remove any other objects that reference it.
    -- For instance, when you remove a body, remove the joints and shapes attached to it.
    --
    -- * Using more iterations or smaller time steps will increase the physics quality, but also increase the CPU usage.

    -- * Chipmunk Constraints
  , Constraint

    -- ** What constraints are and what they are not

    -- | Constraints in Chipmunk are all velocity based constraints.
    -- This means that they act primarily by synchronizing the velocity of two bodies.
    -- A pivot joint holds two anchor points on two separate bodies together by defining equations that say
    -- that the velocity of the anchor points must be the same and calculating impulses to apply to the bodies
    -- to try and keep it that way. A constraint takes a velocity as it’s primary input and produces a velocity change
    -- as its output. Some constraints, (joints in particular) apply velocity changes to correct differences
    -- in positions. More about this in the next section.
    --
    -- A spring connected between two bodies is not a constraint. It’s very constraint-like as it creates forces
    -- that affect the velocities of the two bodies, but a spring takes distances as input and produces forces
    -- as its output. If a spring is not a constraint, then why do I have two varieties of spring constraints you ask?
    -- The reason is because they are damped springs. The damping associated with the spring is a true constraint
    -- that creates velocity changes based on the relative velocities of the two bodies it links.
    -- As it is convenient to put a damper and a spring together most of the time, I figured I might as well just apply
    -- the spring force as part of the constraint instead of having a damper constraint and having the user
    -- calculate and apply their own spring forces separately.

    -- ** Properties

  , constraintBodyA
  , constraintBodyB
  , constraintMaxForce
  , constraintErrorBias
  , constraintMaxBias
  , constraintSpace
  , constraintCollideBodies
  , constraintUserData
  , constraintImpulse

    -- ** Error correction by Feedback

    -- | Joints in Chipmunk are not perfect. A pin joint can’t maintain the exact correct distance between its anchor
    -- points, nor can a pivot joint hold its anchor points completely together. Instead, they are designed
    -- to deal with this by correcting themselves over time. Since Chipmunk 5, you have a fair amount of extra control
    -- over how joints correct themselves and can even use this ability to create physical effects
    -- that allow you to use joints in unique ways:
    --
    -- * Servo motors – Ex: open/close doors or rotate things without going over a maximum force.
    --
    -- * Winches – Pull one object towards another at a constant speed without going over a maximum force.
    --
    -- * Mouse manipulation – Interact with objects smoothly given coarse/shaky mouse input.
    --
    -- There are three properties of 'Constraint' structs that control the error correction,
    -- maxForce, maxBias, and biasCoef. maxForce is pretty self explanatory, a joint or constraint
    -- will not be able to use more than this amount of force in order to function. If it needs more force
    -- to be able to hold itself together, it will fall apart. maxBias is the maximum speed at which error correction
    -- can be applied. If you change a property on a joint so that the joint will have to correct itself,
    -- it normally does so very quickly. By setting a maxSpeed you can make the joint work like a servo,
    -- correcting itself at a constant rate over a longer period of time. Lastly, biasCoef is the percentage
    -- of error corrected every step before clamping to a maximum speed. You can use this
    -- to make joints correct themselves smoothly instead of at a constant speed, but is probably the least useful
    -- of the three properties by far.

    -- ** Constraints and Collision Shapes

    -- | Neither constraints or collision shapes have any knowledge of the other.
    -- When connecting joints to a body the anchor points don’t need to be inside of any shapes attached to the body
    -- and it often makes sense that they shouldn’t. Also, adding a constraint between two bodies
    -- doesn’t prevent their collision shapes from colliding. In fact, this is the primary reason
    -- that the collision group property exists.

    -- ** Video Tour of Current Joint Types

    -- | http://www.youtube.com/watch?v=ZgJJZTS0aMM

    -- ** Shared Memory Management Functions
  , constraintFree

    -- ** Constraint Types

    -- *** Pin Joints
  , pinJointNew

    -- **** Properties
  , pinJointAnchorA
  , pinJointAnchorB
  , pinJointDist

    -- *** Slide Joints
  , slideJointNew

    -- **** Properties
  , slideJointAnchorA
  , slideJointAnchorB
  , slideJointMin
  , slideJointMax

    -- *** Pivot Joints

    -- | (__Note for bindings__: So each instance of pivot joint can be replaced with pin joint with dist of 0?)

  , pivotJointNew
  , pivotJointNew2

    -- **** Properties
  , pivotJointAnchorA
  , pivotJointAnchorB

    -- *** Groove Joint
  , grooveJointNew

    -- **** Properties
  , grooveJointGrooveA
  , grooveJointGrooveB
  , grooveJointAnchorB

    -- *** Damped Spring
  , dampedSpringNew

    -- **** Properties
  , dampedSpringAnchorA
  , dampedSpringAnchorB
  , dampedSpringRestLength
  , dampedSpringStiffness
  , dampedSpringDamping

    -- *** Damped Rotary Spring

    -- | Like a damped spring, but works in an angular fashion.
  , dampedRotarySpringNew

    -- **** Properties
  , dampedRotarySpringRestAngle
  , dampedRotarySpringStiffness
  , dampedRotarySpringDamping

    -- *** Rotary Limit Joint

    -- | Constrains the relative rotations of two bodies.
    -- It is implemented so that it’s possible to for the range to be greater than a full revolution.
  , rotaryLimitJointNew

    -- **** Properties
  , rotaryLimitJointMin
  , rotaryLimitJointMax

    -- *** Ratchet Joint

    -- | Works like a socket wrench.
  , ratchetJointNew

    -- **** Properties
  , ratchetJointAngle
  , ratchetJointPhase
  , ratchetJointRatchet

    -- *** Gear Joint

    -- | Keeps the angular velocity ratio of a pair of bodies constant.
  , gearJointNew

    -- **** Properties
  , gearJointPhase
  , gearJointRatio

    -- *** Simple Motor

    -- | Keeps the relative angular velocity of a pair of bodies constant.
    -- You will usually want to set an force (torque) maximum for motors as otherwise
    -- they will be able to apply a nearly infinite torque to keep the bodies moving.
  , simpleMotorNew

    -- **** Properties
  , simpleMotorRate

    -- ** Notes

    -- | * You can add multiple joints between two bodies, but make sure that they don’t fight.
    -- Doing so can cause the bodies jitter or spin violently.

    -- * Overview of Collision Detection in Chipmunk

    -- | In order to make collision detection in Chipmunk as fast as possible, the process is broken down
    -- into several stages. While I’ve tried to keep it conceptually simple, the implementation can be a bit daunting.
    -- Fortunately as a user of the library, you don’t need to understand everything about how it works.
    -- Though if you are trying to squeeze every bit of performance out of Chipmunk, understanding this section
    -- can be helpful.

    -- ** Spatial Indexing

    -- | A for loop that checks every object against every other object in the scene would be very slow.
    -- So the first stage of the collision detection, commonly called the broadphase, uses a high level
    -- spatial algorithm to decide which pairs of objects to check for collisions.
    -- Currently Chipmunk supports two spatial indexes, an axis-aligned bounding box tree and a spatial hash.
    -- These spatial indexes are able to quickly identify which pairs of shapes are near each other
    -- and should be checked for a collision.

    -- ** Fast Collision Filtering

    -- | After the spatial index figures out which pairs of shapes are likely to be near each other,
    -- it passes each pair back to the space using a callback to perform some additional filtering on the pairs.
    -- Before doing anything else, Chipmunk performs a few quick tests to check if shapes should collide.
    --
    -- * __Bounding Box Test__: The shapes are not colliding if their bounding boxes are not overlapping.
    -- Objects like diagonal line segments can trigger a lot of false positives here,
    -- but it’s unlikely to be something you should worry about.
    --
    -- * __Category Mask Test__: The categories of each shape are bitwise ANDed against the category mask
    -- of the other shape. If either result is 0, the shapes do not collide.
    --
    -- * __Group Test__: Shapes shouldn’t collide with other shapes in the same non-zero group.

    -- ** Constraint Based Filtering

    -- | After fast collision filtering, Chipmunk checks the list of joints on one of the bodies
    -- to see if it has a constraint that attaches it to the other body. If that constraint’s collideBodies
    -- property is false, the collision will be ignored. This check is often very fast
    -- since most scenes don’t contain a lot of constraints.

    -- ** Primitive Shape to Shape Collision Detection

    -- | The most expensive test is to actually check for overlap based on their geometry.
    -- Circle to circle and circle to line collisions are very fast. Segment to segment and poly to poly collisions
    -- are handled using the GJK/EPA algorithms, and get more expensive as the number of vertexes increases.
    -- Simpler shapes make for faster collisions, and often more important, fewer collision points
    -- for the solver to run. Chipmunk uses a small dispatch table to figure out which function to use to check
    -- if the shapes overlap.
    --
    -- Without going into too much detail, the GJK algorithm checks the distance between two objects,
    -- and the EPA algorithm checks how much they are overlapping. If you give you segment and poly shapes
    -- a small radius when creating them, the EPA algorithm can usually be skipped, speeding up the collision detection
    -- considerably. The radius should be at least as big as the amount of allowed collision slop.

    -- ** Collision Handler Filtering

    -- | After checking if two shapes overlap Chipmunk will look to see if you have defined a collision handler
    -- for the collision types of the shapes. This is vital to process collisions events for the gameplay,
    -- but also gives you a very flexible way to filter out collisions. The return value of the begin and preSolve
    -- callbacks determines whether or not the colliding pair of shapes is discarded or not.
    -- Returning true will keep the pair, false will discard it. Rejecting a collision from a begin callback
    -- is permanent, rejecting it from the preSolve only applies to the step it occured in. If you don’t define
    -- a handler for the given collision types, Chipmunk will call the space’s default handler, which by default
    -- is defined to simply accept all collisions.
    --
    -- Wildcard collisions can also return a value, but they are handled in a more complicated way.
    -- When you create a collision handler between two specific collision types, it’s your responsibility
    -- to decide when to call the wildcard handlers and what to do with their return values.
    -- Otherwise, the default is to call the wildcard handler for the first type, then the second type,
    -- and use a logical AND of their return values as filtering value. See DefaultBegin() in cpSpace.c
    -- for more information.
    --
    -- While using callbacks to filter collisions is the most flexible way, keep in mind that by the time your callback
    -- is called all of the most expensive collision detection has already been done. For simulations
    -- with a lot of colliding objects each frame, the time spent finding collisions is small compared to the time
    -- spent solving the physics for them so it may not be a big deal. Fast collision filtering should be preferred
    -- if possible.

    -- * Collision Callbacks

    -- | A physics library without any events or feedback would not be very useful for games.
    -- How would you know when the player bumped into an enemy so that you could take some health points away?
    -- How would you know how hard the car hit something so you don’t play a loud crash noise when a pebble hits it?
    -- What if you need to decide if a collision should be ignored based on specific conditions,
    -- like implementing one way platforms? Chipmunk has a number of powerful callback systems
    -- that you can use to solve these problems.

    -- ** Collision Handlers

    -- | Collision handler function types. While all of them take an arbiter, space, and a user data pointer,
    -- only the begin and preSolve callbacks return a value. See above for more information.
  , CollisionCallback
    -- Collision callbacks are closely associated with 'Arbiter' structs.
    -- You should familiarize yourself with those as well.
    --
    -- __Note__: Shapes tagged as sensors (cpShape.sensor == true) never generate collisions that get processed,
    -- so collisions between sensors shapes and other shapes will never call the postSolve callback.
    -- They still generate begin, and separate callbacks, and the preSolve callback is also called
    -- every frame even though there is no collision response.
    --
    -- __Note #2__: preSolve callbacks are called before the sleeping algorithm runs.
    -- If an object falls asleep, its postSolve callback won’t be called until it’s reawoken.

  , CollisionType
  , CollisionHandler (..)
  , CollisionHandlerPtr
  , spaceAddCollisionHandler
  , spaceAddWildcardHandler
  , spaceAddDefaultCollisionHandler
  , modifyCollisionHandler
  , mkCallback
  , mkCallbackB

    -- ** Post-Step Callbacks

    -- | Post-step callbacks are the one place where you can break the rules about adding or removing objects
    -- from within a callback. In fact, their primary function is to help you safely remove objects from the space
    -- that you wanted to disable or destroy in a collision or query callback.
    --
    -- Post step callbacks are registered as a function and a pointer that is used as a key.
    -- You can only register one postStep callback per key. This prevents you from accidentally removing
    -- an object more than once. For instance, say that you get a collision callback between a bullet and object A.
    -- You want to destroy both the bullet and object A, so you register a postStep callback
    -- to safely remove them from your game. Then you get a second collision callback between the bullet and object B.
    -- You register a postStep callback to remove object B, and a second postStep callback to remove the bullet.
    -- Because you can only register one callback per key, the postStep callback for the bullet
    -- will only be called once and you can’t accidentally try to remove it twice.
  , PostStepFunc
  , spaceAddPostStepCallback

    -- ** Examples

    -- | See
    -- <https://chipmunk-physics.net/release/ChipmunkLatest-Docs/examples.html#CollisionCallbacks the callback examples>
    -- for more information.

    -- * Chipmunk Collision Pairs
  , Arbiter

    -- ** Memory Management

    -- | You will never need to create or free an arbiter. More importantly,
    -- because they are entirely managed by the space you should never store a reference to an arbiter
    -- as you don’t know when they will be freed or reused. Use them within the callback where they are given to you
    -- and then forget about them or copy out the information you need.

    -- ** Properties

  , arbiterRestitution
  , arbiterFriction
  , arbiterSurfaceVelocity
  , arbiterUserData

    -- *** Collision Point(s)
  , arbiterCount
  , arbiterNormal
  , arbiterPointA
  , arbiterPointB
  , arbiterDepth

    -- *** Other
  , arbiterIsFirstContact
  , arbiterIsRemoval

    -- *** Bodies and shapes
  , arbiterShapes
  , arbiterBodies

    -- *** Running wildcard handlers

    -- | These functions invoke the wildcard handlers for a given collision. For custom collision handlers
    -- between specific types or overriding the default handler, you must decide how to invoke the wildcard handlers
    -- since it may be important to call the wildcards first, last, or possibly skip them entirely.
    -- For the begin and preSolve callbacks, you also need to decide what to do with their return values
    -- since they may not agree with each other or the specific handler they were called from.
    -- Every collision handler is defined for two types, the “A” variants of these functions call the wildcard handler
    -- for the first type, and the “B” variants call the handler for the second type.

  , arbiterCallWildcardBeginA
  , arbiterCallWildcardBeginB
  , arbiterCallWildcardPreSolveA
  , arbiterCallWildcardPreSolveB
  , arbiterCallWildcardPostSolveA
  , arbiterCallWildcardPostSolveB
  , arbiterCallWildcardSeparateA
  , arbiterCallWildcardSeparateB

    -- * Misc
  , DataPtr
  , Transform (..)

    -- * Re-exports
  , nullPtr
  , HasGetter (..)
  , HasSetter (..)
  ) where

import Foreign
import Data.StateVar

import Chiphunk.Low.Types
import Chiphunk.Low.Math
import Chiphunk.Low.Helper
import Chiphunk.Low.Vect
import Chiphunk.Low.BB
import Chiphunk.Low.Body
import Chiphunk.Low.Shape
import Chiphunk.Low.Space
import Chiphunk.Low.Constraint
import Chiphunk.Low.Callback
import Chiphunk.Low.Arbiter