Why would I ever need to cancelAnimationFrame()

Question

I don't understand why the API includes cancelAnimationFrame(), because I can stop the animation by setting the continue variable like this:

function draw(timestamp) {
  if (continue == true) { requestAnimationFrame(draw); }
}

So the questions is under what circumstances should I use cancelAnimationFrame()?

Answer 1

First, an important point of reference. A (dated) (Candidate Recommendation) Spec: http://www.w3.org/TR/animation-timing/#definitions

Associated with every Document is an animation frame request callback list, which is a list of tuples. handle is an integer ^[long] that uniquely identifies the entry in the list. callback is a FrameRequestCallback object. Initially, the animation frame request callback list for a Document is empty.

Also, lets bear in mind that the target audience of these specs are user-agent developers. It's in the implemention of these specs that user-agent provides an API to us (app developers) to interface with/to.

Note the every Document sentiment above; you can have multible documents in a window, or context. You can have multiple contexts in a browsing context.

So, how does that relate to every Document? Well, the (Recommendation) spec references the Process Model, which essentially dumps all these lists into an empty list, and perform a callback invoking algorithm on the results of that 'preserved' list.. but, again, this is probably not a concern to us as app developers; *I THINK, we, as app developers, aren't going to be tracking and maintaining even Document.FrameRequestList instances in and throughout multiple documents of our own window context. We just interface with the API, which is accessible on window.

Now, lets summarize what requestAnimationFrame(<function>) does in effect, AND what it returns.

Calling requestAnimationFrame and providing a function as a callback, adds an entry (<handler,FrameRequestCallback> or <long, "an object, with a cancelled member, that encapsulates your function">) into an animation frame request callback list. requestAnimationFrame returns the Handler [long].

According to the aforementioned spec (http://www.w3.org/TR/animation-timing/#dom-windowanimationtiming-cancelanimationframe),

The cancelAnimationFrame method is used to cancel a previously made request to schedule an animation frame update.

One can infer, that by calling cancelAnimationFrame and supplying the (presumably previously stored) handle as a parameter, you remove an entry from the animation frame request callback list, BUT that isn't the case.

When cancelAnimationFrame(handle) is called, the user agent must set the cancelled flag to true for the callback registered on this Document whose handle is handle. The cancelled flag is set whether the callback is in a animation frame request callback list or not. If there is no callback with the given handle, then this function does nothing.

So the handle you provide in your cancelAnimationFrame doesn't modify the list. it sets the cancelled flag to true 'on the callback'.. which really keeps it from running. This is reasonable because the aforementioned (above) Processing Model.

---

So, to your question (and in regards to a particular comment on your question) skipping over the adding of an entry to an animation frame request callback list of a document, using requestAnimationFrame doesn't keep existing scheduled entries (or existing entries whose cancelled flag is false) from running. There is a 'larger' context and processing model to consider (which includes document-page visibility attributes).

It was mentioned as a comment in your question that there are particular scenerios that you might want to cancel the schedule frame requests - but better reasoning to do it is for the unintentional aspects and considerations.

In short, if you're going to use the API to request frame updates that do callbacks, use the API to cancel/stop said update requests and stop the callback.