This documents the full API of Shared Motion.

<!-- Import Motion Corporation services -->
<script type="text/javascript" src="http://www.mcorp.no/lib/mcorp-2.0.js"></script>

Query returns the current state of the motion. It is a local, inexpensive operation. Use frequently.

var snapshot = motion.query();

var pos = snapshot.pos; // position
var vel = snapshot.vel; // velocity
var acc = snapshot.acc; // acceleration
var ts = snapshot.ts; // timestamp

You may also access properties of the motion directly by using getters.

// Warning : getters do not draw values from the same snapshot!
var pos = motion.pos; // position
var vel = motion.vel; // velocity
var acc = motion.acc; // acceleration

Update changes the current state of the motion. It is a remote operation. Use infrequently.

var sent = motion.update(new_pos, new_vel, new_acc);

The update operation changes the motion by supplying new initial conditions for the motion. update(0.0, 1.0, 0.0) means play from start. update(8.0, -1.0, 0.0) means play backwards from position 8.0. Motions can also be partially changed. For example, update(null, 0.0, 0.0) means pause where you are, whereas update(null, 1.0, 0.0) means resume.

The return value of update simply states whether a request has been sent to the remote server or not. In particular, it does NOT indicate that the operations has been performed. Strictly speaking, it doesn't even guarantee that the update will be performed. The effects of update operations are available through the "change" event (see below).

Please note that update is a remote operation. It involves updating an object on a motion server somewhere far-far away. Additionally it involves updating all clients who are currently sharing this motion. For this reason, you should not expect to see the effects of the Update immediately. The Update latency is about 1 RTT (round-trip-time) (less than 0.2 seconds under decent network conditions). Use update sparingly. In particular, avoid frequent updates of the position in order to emulate motion. This defeates the basic motivation for the concept. Instead, use velocity.

Motions provide three event types; "change", "readystatechange" and "timeupdate". All these event types can be listened to using the on/off operations.

var handler = function (e) {};
motion.on("change", handler);
motion.off("change", handler); 

Within event handlers this is bound to the motion that was the source of the event.

The "change" event is invoked in two circumstances

1. Immediately after the event handler is registered with the motion
2. Whenever the motion is changed by an update

The purpose of the "immediate" event is to simplify life for the programmer. Motion always guarantees that initial state will be provided first, followed by subsequent state changes. This guarantee is maintained independent of when the handler is registered.

Event argument e is a new snapshot from the motion, equal to a snapshot derived from query().

The "timeupdate" event is analogous to the event you would expect from media elements and media controllers. The "timeupdate" event fires periodically, with a fixed frequency of 5Hz (i.e. every 200ms). While motion is paused (i.e., zero velocity), "timeupdate" will not fire. In addition, "timeupdate" fires with every "change" event. Finally, "timeupdate" provides an "immediate" event upon handler registration, just like the "change" event.

Event argument e is a new snapshot from the motion, equal to a snapshot derived from query().

The "readystatechange" event fires whenever the the motion.readyState changes. This event is useful for instance for detecting that the motion is temporarily offline. Event argument e is the new value of the motion.readyState property. Read more about readystate below.

Motions provide a readyState property. This property allows programmers to know when motions are ready to use, or if they are temporarily disconnected. Motions automatically reconnect after lost connections. For instance, this allows mobile devices to switch seamlessly between networks.

// STATE definitions
motion.STATE = Object.freeze({
    INIT : "init",
    CONNECTING: "connecting",
    EXPIRED: "expired",
    OPEN: "open",
    CLOSED: "closed"
  });
motion.readyState // getter
motion.on("readystatechange", handler);

// example
if (motion.readyState === motion.STATE["OPEN"]) {
  // motion ready to use
}

• INIT : initial state
• OPEN : ready to use
• CLOSED : terminal state
• EXPIRED : access to motion expired
• CONNECTING : not online, will reconnect

var info = motion.getInfo(); 

info.readyState // readystate
info.latency    // network latency /sec) (RTT/2)
info.skew       // diff (sec) between client and server clock
info.connType   // network connection ("ws" | "http")
info.range      // range of the motion, e.g. [0,100]
info.src        // URL of motion
info.cred       // credentials of client ("r" |"rw")
info.vector     // initial vector for current movement [p,v,a,t]
info.lastVector // initial vector for previous movement [p,v,a,t]

motion.readyState // readystate value
motion.STATE      // map of legal readyStates
motion.src        // URL of the motion
motion.pos        // current position
motion.vel        // current velocity
motion.acc        // current acceleration