Senin, 02 Desember 2024

Timing control for script-based animations W3C Working Draft 21 February 2012

 

1. Introduction

This section is informative.

Animations in web browsers come in two forms: native, declarative ones, such as the <animate> element in SVG, and those that are implemented in script. These script-based animations are most often performed by scheduling a callback using setTimeout or setInterval and making changes to the DOM to effect the animation in that callback.

A disadvantage of this approach is that the author of the animation script has no idea what the ideal frequency for updating their animation is. Instead, the easiest way forward for the author is to simply call setTimeout with a very small value, which in practice will be clamped to some minimum time like 10ms anyway. It likely won’t be the case that 100 updates per second are required for the animation, especially if the page is in a background tab or the browser window is minimized.

The API described in this document allows script authors to request the user agent schedule an animation frame update. The user agent is in a better position to determine how many frames per second to allocate to all of the animations running in the entire browser. If there are many animations active, the user agent can select a frame rate such that all of the animations will run as smoothly as possible. If the page is not currently visible, animations on that page can be throttled heavily so that they do not update often and thus consume little CPU power.

Example

Here is an example of using the API to write a script-based animation.

HTML
<!DOCTYPE html>
<title>Script-based animation using requestAnimationFrame</title>
<style>
div { position: absolute; left: 10px; padding: 50px;
  background: crimson; color: white }
</style>
<script>
var requestId = 0;

function animate(time) {
  document.getElementById("animated").style.left =
    (time - animationStartTime) % 2000 / 4 + "px";
  requestId = window.requestAnimationFrame(animate);
}
function start() {
  animationStartTime = Date.now();
  requestId = window.requestAnimationFrame(animate);
}
function stop() {
  if (requestId)
    window.cancelAnimationFrame(requestId);
  requestId = 0;
}
</script>
<button onclick="start()">Click me to start!</button>
<button onclick="stop()">Click me to stop!</button>
<div id="animated">Hello there.</div>

2. Conformance

Everything in this specification is normative except for diagrams, examples, notes and sections marked as being informative.

The keywords “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may” and “optional” in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels. [RFC2119]

The IDL fragment in section 4 of this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

This specification defines a single conformance class:

conforming user agent
A user agent is considered to be a conforming user agent if it satisfies all of the must-, required- and shall-level criteria in this specification. A conforming user agent must also be a conforming implementation of the IDL fragment in section 4 of this specification, as described in the Web IDL specification. [WEBIDL]

This specification references interfaces and types from a number of other specifications:

3. Definitions

Associated with every Document is an animation frame request callback list, which is a list of <handle, callback> tuples. handle is an integer 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.

A Document is said to have active animations whenever it has a non-empty animation frame request callback list.

4. The WindowAnimationTiming interface

The WindowAnimationTiming interface is used to expose the requestAnimationFrame operation on the Window object. In the definition of requestAnimationFrame below, references to the Document object are to be taken to be references to the Window object’s active document. [HTML5]

[NoInterfaceObject]
interface WindowAnimationTiming {
  long requestAnimationFrame(FrameRequestCallback callback);
  void cancelAnimationFrame(long handle);
};

Window implements WindowAnimationTiming;

callback FrameRequestCallback = void (DOMTimeStamp time);

The requestAnimationFrame method is used to signal to the user agent that a script-based animation needs to be resampled. When requestAnimationFrame(callback) is called, the user agent must schedule a script-based animation resampling by appending to the end of the animation frame request callback list an entry whose handle is a user-agent-defined integer greater than zero that uniquely identifies the entry in the list and whose callback is callback.

Each FrameRequestCallback object has a cancelled boolean flag. This flag is initially false and is not exposed by any interface.

Note

requestAnimationFrame only schedules a single update to the script-based animation. If subsequent animation frames are needed, then requestAnimationFrame will need to be called again from within the callback.

Also note that multiple calls to requestAnimationFrame with the same callback (before callbacks are invoked and the list is cleared) will result in multiple entries being in the list with that same callback, and thus will result in that callback being invoked more than once for the animation frame.

Editorial note

ISSUE-4 Do we want to allow an Element to be passed to requestAnimationFrame, so that animations affecting the given element are throttled or paused when scrolled out of view?

The cancelAnimationFrame method is used to cancel a previously made request to schedule an animation frame update. 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.

Note

cancelAnimationFrame might be called for an entry in the Document’s animation frame request callback list or in the sample all animations operation’s temporary list. In either case the entry’s cancelled flag is set to true so that the callback does not run.

5. Processing Model

Whenever a Document's hidden attribute is false and the animation frame request callback list is not empty, the user agent MUST regularly queue a task that samples all animations for that Document's top-level browsing context. The task source for these tasks is the animation task source. Only one task should be generated per top-level browsing context, even if multiple Documents within the same top-level browsing context are not hidden and contain callbacks. To samples all animations , the following steps are performed:
  1. Let t be the result of getting the next sample time of the top-level browsing context.
    Editorial note

    ISSUE-2 Getting the next sample time is currently undefined. This time should be the same as the time that contemporaneous native animations have been sampled at.

  2. Let time be t expressed as the number of milliseconds since 1970-01-01T00:00:00Z.
    Editorial note

    ISSUE-3 Having animation frame times run off a monotonic clock that increases at a constant rate would be better for authors than using the wallclock time as reported by the system, which might jump backwards or move forwards at varying rates due to clock slew. Doing this argues for the reinclusion of the Window.animationStartTime attribute that was present in an earlier draft, so that scripts can avoid using Date.now() to record the animation start time, which might bear little relation to the monotonic clock values anyway.

  3. Let list be an empty animation frame request callback list.
  4. Let contexts be the results of list of the descendant browsing contexts algorithm for this task's top-level browsing context.
  5. For every context in contexts, in any order, perform the following steps:
    1. Let d be context's active document.
    2. If d's hidden attribute is true, continue to the next entry in the contexts list. Otherwise proceed with these steps.
    3. Let doclist be d's animation frame request callback list.
    4. Append all entries from doclist into list preserving order.
    5. Clear doclist.
  6. Perform the steps defined in the invoke callbacks algorithm with parameters list and time

The invoke callbacks algorithm:

  1. For each entry callback in list, in order:
    1. If the cancelled flag on callback is not true:
      1. Call callback with time as the argument.
      2. If calling the operation resulted in an exception being thrown, then catch that exception and ignore it.
Note

The expectation is that the user agent will run tasks from the animation task source at at a regular interval matching the display's refresh rate. Running tasks at a lower rate can result in animations not appearing smooth. Running tasks at a higher rate can cause extra computation to occur without a user-visible benefit.

6. Acknowledgements

This section is informative.

The editors would like to thank the following people for contributing to this specification: Boris Zbarsky, Jonas Sicking, Robert O’Callahan.

A. References

A.1. Normative references

[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 7 April 2004. This version of the Document Object Model Level 3 Core Recommendation is http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407. The latest version of DOM Core is available at http://www.w3.org/TR/domcore/.
[HTML5]
HTML5, Ian Hickson, Editor. World Wide Web Consortium, May 2011. This version of the HTML5 is available from http://www.w3.org/TR/html5/. The latest editor's draft is available at http://dev.w3.org/html5/spec/.
[Web IDL]
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, February 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/WD-WebIDL-20120207/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.

A.2. Informative references

Diposting oleh di

Tidak ada komentar:

Posting Komentar

Langganan: Posting Komentar (Atom)