ClutterBox2D Joint

ClutterBox2D Joint — Joint creation and manipulation.

Synopsis

                    ClutterBox2DJoint;
void                clutter_box2d_joint_destroy         (ClutterBox2DJoint *joint);
ClutterBox2DJoint * clutter_box2d_add_revolute_joint    (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble reference_angle);
ClutterBox2DJoint * clutter_box2d_add_revolute_joint2   (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor);
ClutterBox2DJoint * clutter_box2d_add_distance_joint    (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble length,
                                                         gdouble frequency,
                                                         gdouble damping_ratio);
ClutterBox2DJoint * clutter_box2d_add_prismatic_joint   (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble min_length,
                                                         gdouble max_length,
                                                         const ClutterVertex *axis);
ClutterBox2DJoint * clutter_box2d_add_mouse_joint       (ClutterBox2D *box2d,
                                                         ClutterActor *actor,
                                                         const ClutterVertex *target);
void                clutter_box2d_mouse_joint_update_target
                                                        (ClutterBox2DJoint *mouse_joint,
                                                         const ClutterVertex *target);

Description

Joints connects actors. Joints can be manually destroyed, if they are not manually destroyed they are destroyed when one of the member actors of the joint is destroyed.

Details

ClutterBox2DJoint

typedef struct _ClutterBox2DJoint ClutterBox2DJoint;

A handle refering to a joint in a ClutterBox2D container, joints are automatically memory managed by Box2D and get destroyed if any of the actors invovled in the joint is destroyed. You may also explicitly free the joint by calling clutter_box2d_joint_destroy on a joint that is no longer needed.


clutter_box2d_joint_destroy ()

void                clutter_box2d_joint_destroy         (ClutterBox2DJoint *joint);

Destroys a ClutterBox2DJoint, call this function manually to remove a joint that you no longer have need for. Note that it is mostly not neccesary to destroy joints that are part of models manually since they will be destroyed automatically when the actors they use are destroyed.

joint :

A ClutterBox2DJoint

clutter_box2d_add_revolute_joint ()

ClutterBox2DJoint * clutter_box2d_add_revolute_joint    (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble reference_angle);

Create a revolute joint. A revolute joint defines a coordinates on two actors that should coincide. The actors are allowed to rotate around this point making it act like an axle.

box2d :

a ClutterBox2D

actor1 :

first actor participating in joint

actor2 :

second actor participating in joint

anchor1 :

the local coordinates for the common point on actor1

anchor2 :

the local coordinates fro the common point on actor2

reference_angle :

the initial relative angle for joint limit (currently unused)

Returns :

a ClutterBox2DJoint handle or NULL on error.

clutter_box2d_add_revolute_joint2 ()

ClutterBox2DJoint * clutter_box2d_add_revolute_joint2   (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor);

Create a revolute joint that is defined by original positions of actors and a common point specified in world coordinates.

box2d :

a ClutterBox2D

actor1 :

first actor participating in joint

actor2 :

second actor participating in joint

anchor :

the world (box2d container) coordinates for the point that actor1 and actor2 are allowed to revolve around.

Returns :

a ClutterBox2DJoint handle or NULL on error.

clutter_box2d_add_distance_joint ()

ClutterBox2DJoint * clutter_box2d_add_distance_joint    (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble length,
                                                         gdouble frequency,
                                                         gdouble damping_ratio);

A distance joint constrains two points on two bodies to remain at a fixed distance from each other. You can view this as a massless, rigid rod. By modifying frequency and damping_ratio you can achieve a spring like behavior as well. The defaults for frequency and damping_ratio to disable dampening is 0.0 for both.

box2d :

a ClutterBox2D

actor1 :

first actor participating in joint

actor2 :

second actor participating in joint

anchor1 :

the local coordinates for the common point on actor1

anchor2 :

the local coordinates fro the common point on actor2

length :

the length that the simulation will maintain between anchor1 on actor1 and anchor2 on actor2.

frequency :

the frequency of length updates.

damping_ratio :

the damping ratio.

Returns :

a ClutterBox2DJoint handle or NULL on error.

clutter_box2d_add_prismatic_joint ()

ClutterBox2DJoint * clutter_box2d_add_prismatic_joint   (ClutterBox2D *box2d,
                                                         ClutterActor *actor1,
                                                         ClutterActor *actor2,
                                                         const ClutterVertex *anchor1,
                                                         const ClutterVertex *anchor2,
                                                         gdouble min_length,
                                                         gdouble max_length,
                                                         const ClutterVertex *axis);

A prismatic joint. This joint provides one degree of freedom: translation along an axis fixed in body1. Relative rotation is prevented.

box2d :

a ClutterBox2D

actor1 :

first actor participating in joint

actor2 :

second actor participating in joint

anchor1 :

the local coordinates for the common point on actor1

anchor2 :

the local coordinates fro the common point on actor2

min_length :

minimum distance between anchor points

max_length :

maximum distance between anchor points.

axis :

the local translation axis in body1.

Returns :

a ClutterBox2DJoint handle or NULL on error.

clutter_box2d_add_mouse_joint ()

ClutterBox2DJoint * clutter_box2d_add_mouse_joint       (ClutterBox2D *box2d,
                                                         ClutterActor *actor,
                                                         const ClutterVertex *target);

A mouse joint is used to make a point on a dynamic actor track a specified world point. This a soft constraint with a maximum force. This allows the constraint to stretch and without applying huge forces.

box2d :

a ClutterBox2D

actor :

the (dynamic) actor to be manipulated.

target :

the box2d container coordinates of the mouse.

Returns :

a ClutterBox2DJoint handle or NULL on error.

clutter_box2d_mouse_joint_update_target ()

void                clutter_box2d_mouse_joint_update_target
                                                        (ClutterBox2DJoint *mouse_joint,
                                                         const ClutterVertex *target);

Updates the position the the target point should coincide with. By updating this in a motion event callback for mouse motion physical interaction with dynamic actors is possible.

mouse_joint :

A ClutterBox2DJoint priorly returned from clutter_box2d_add_mouse_joint.

target :

new box2d container coordinates for mouse pointer.