## ClutterBehaviourBspline

ClutterBehaviourBspline — A behaviour interpolating position along a B-Spline

## Synopsis

                        ClutterBehaviourBspline;
                        ClutterBehaviourBsplineClass;
    ClutterBehaviour *  clutter_behaviour_bspline_new       (ClutterAlpha *alpha,
                                                             const ClutterKnot *knots,
                                                             guint n_knots);
    void                clutter_behaviour_bspline_append_knot
                                                            (ClutterBehaviourBspline *bs,
                                                             const ClutterKnot *knot);
    void                clutter_behaviour_bspline_append_knots
                                                            (ClutterBehaviourBspline *bs,
                                                             const ClutterKnot *first_knot,
                                                             ...);
    void                clutter_behaviour_bspline_truncate  (ClutterBehaviourBspline *bs,
                                                             guint offset);
    void                clutter_behaviour_bspline_join      (ClutterBehaviourBspline *bs1,
                                                             ClutterBehaviourBspline *bs2);
    ClutterBehaviour *  clutter_behaviour_bspline_split     (ClutterBehaviourBspline *bs,
                                                             guint offset);
    void                clutter_behaviour_bspline_clear     (ClutterBehaviourBspline *bs);
    void                clutter_behaviour_bspline_adjust    (ClutterBehaviourBspline *bs,
                                                             guint offset,
                                                             ClutterKnot *knot);
    void                clutter_behaviour_bspline_set_origin
                                                            (ClutterBehaviourBspline *bs,
                                                             ClutterKnot *knot);
    void                clutter_behaviour_bspline_get_origin
                                                            (ClutterBehaviourBspline *bs,
                                                             ClutterKnot *knot);

## Object Hierarchy

      GObject
       +----ClutterBehaviour
             +----ClutterBehaviourBspline

## Implemented Interfaces

ClutterBehaviourBspline implements

## Signals

      "knot-reached"                                   : Run Last

## Description

ClutterBehaviourBspline interpolates actors along a defined B-Spline path.

A bezier spline is a set of cubic bezier curves defined by a sequence of control points given when creating a new ClutterBehaviourBspline instance.

Additional bezier curves can be added to the end of the bspline using clutter_behaviour_bspline_append_* family of functions, control points can be moved using `clutter_behaviour_bspline_adjust()`. The bspline can be split into two with `clutter_behaviour_bspline_split()`, and bsplines can be concatenated using `clutter_behaviour_bspline_join()`.

Each time the behaviour reaches a point on the path, the "knot-reached" signal is emitted.

## Details

### ClutterBehaviourBspline

    typedef struct _ClutterBehaviourBspline ClutterBehaviourBspline;

ClutterBehaviourBspline contains only private data and should be accessed using the functions below.

Since 0.2

### ClutterBehaviourBsplineClass

    typedef struct {
      void (*knot_reached) (ClutterBehaviourBspline *bsplineb,
                            const ClutterKnot       *knot);
    } ClutterBehaviourBsplineClass;

ClutterBehaviourBsplineClass contains only private data and should be accessed using the functions below.

`knot_reached` () | class handler for the "knot-reached" signal

Since 0.2

### clutter_behaviour_bspline_new ()

    ClutterBehaviour *  clutter_behaviour_bspline_new       (ClutterAlpha *alpha,
                                                             const ClutterKnot *knots,
                                                             guint n_knots);

Creates a new bezier spline behaviour. You can use this behaviour to drive actors along the bezier spline, described by the `knots` control points.

Bspline is defined by 3n + 1 points, n >=1; any trailing points passed into this function are stored internally and used during any subsequent clutter_behaviour_bspline_append_* operations.

`alpha` : | a ClutterAlpha, or `NULL`
`knots` : | a list of ClutterKnots representing individual control points
`n_knots` : | the number of control points
Returns : | a ClutterBehaviour

Since 0.4

### clutter_behaviour_bspline_append_knot ()

    void                clutter_behaviour_bspline_append_knot
                                                            (ClutterBehaviourBspline *bs,
                                                             const ClutterKnot *knot);

Appends a ClutterKnot control point to the bezier spline bs. Note, that since a bezier is defined by 4 control points, the point gets stored in a temporary chache, and only when there are enough control points to create a new bezier curve will the bspline extended.

`bs` : | a ClutterBehaviourBspline
`knot` : | a ClutterKnot control point to append.

Since 0.4

### clutter_behaviour_bspline_append_knots ()

    void                clutter_behaviour_bspline_append_knots
                                                            (ClutterBehaviourBspline *bs,
                                                             const ClutterKnot *first_knot,
                                                             ...);

Appends a bezier spline defined by the last control point of bezier spline bs and the array of ClutterKnot control points to the orginal bezier spline bs.

`bs` : | a ClutterBehaviourBspline
`first_knot` : | first ClutterKnot
`...` : | a NULL-terminated array of ClutterKnot control points.

Since 0.6

### clutter_behaviour_bspline_truncate ()

    void                clutter_behaviour_bspline_truncate  (ClutterBehaviourBspline *bs,
                                                             guint offset);

Truncates the bezier spline at the control point; if the control point at offset is not one of the on-curve points, the bspline will be truncated at the nearest preceeding on-curve point.

`bs` : | a ClutterBehaviourBspline
`offset` : | offset of control where the bspline should be truncated

Since 0.4

### clutter_behaviour_bspline_join ()

    void                clutter_behaviour_bspline_join      (ClutterBehaviourBspline *bs1,
                                                             ClutterBehaviourBspline *bs2);

Joins a copy of bezier spline bs2 onto the end of bezier spline bs1; bs2 is not modified.

`bs1` : | a ClutterBehaviourBspline
`bs2` : | a ClutterBehaviourBspline

Since 0.4

### clutter_behaviour_bspline_split ()

    ClutterBehaviour *  clutter_behaviour_bspline_split     (ClutterBehaviourBspline *bs,
                                                             guint offset);

Splits a bezier spline into two at the control point at offset; if the control point at offset is not one of the on-curve bezier points, the bspline will be split at the nearest on-curve point before the offset. The original bspline is shortened appropriately.

`bs` : | a ClutterBehaviourBspline
`offset` : | an offset of the control point at which to split the spline.
Returns : | new ClutterBehaviourBspline.

Since 0.4

### clutter_behaviour_bspline_clear ()

    void                clutter_behaviour_bspline_clear     (ClutterBehaviourBspline *bs);

Empties a bspline.

`bs` : | a ClutterBehaviourBspline

Since 0.4

### clutter_behaviour_bspline_adjust ()

    void                clutter_behaviour_bspline_adjust    (ClutterBehaviourBspline *bs,
                                                             guint offset,
                                                             ClutterKnot *knot);

Change the coordinaces of control point at index to those represented by the knot.

`bs` : | a ClutterBehaviourBspline
`offset` : | an index of control point to ajdust
`knot` : | a ClutterKnot with new coordinances for the control point.

Since 0.4

### clutter_behaviour_bspline_set_origin ()

    void                clutter_behaviour_bspline_set_origin
                                                            (ClutterBehaviourBspline *bs,
                                                             ClutterKnot *knot);

Sets the origin of the bezier to the point represented by knot. (Initially the origin of a bspline is given by the position of the first control point of the first bezier curve.)

`bs` : | a ClutterBehaviourBspline
`knot` : | a ClutterKnot origin for the bezier

Since 0.4

### clutter_behaviour_bspline_get_origin ()

    void                clutter_behaviour_bspline_get_origin
                                                            (ClutterBehaviourBspline *bs,
                                                             ClutterKnot *knot);

Gets the origin of the bezier.

`bs` : | a ClutterBehaviourBspline
`knot` : | a ClutterKnot where to store the origin of the bezier

Since 0.4

## Signal Details

### The `"knot-reached"` signal

    void                user_function                      (ClutterBehaviourBspline *pathb,
                                                            ClutterKnot             *knot,
                                                            gpointer                 user_data)      : Run Last

This signal is emitted at the end of each frame.

`pathb` : | the object which received the signal
`knot` : | the ClutterKnot reached
`user_data` : | user data set when the signal handler was connected.

Since 0.2