diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/cancelanimationframe/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/cancelanimationframe/index.md new file mode 100644 index 000000000000000..38e115f92d8f17d --- /dev/null +++ b/files/en-us/web/api/dedicatedworkerglobalscope/cancelanimationframe/index.md @@ -0,0 +1,97 @@ +--- +title: "DedicatedWorkerGlobalScope: cancelAnimationFrame() method" +short-title: cancelAnimationFrame() +slug: Web/API/DedicatedWorkerGlobalScope/cancelAnimationFrame +page-type: web-api-instance-method +browser-compat: api.DedicatedWorkerGlobalScope.cancelAnimationFrame +--- + +{{APIRef}} + +The **`cancelAnimationFrame()`** method of the {{domxref("DedicatedWorkerGlobalScope")}} interface cancels an animation frame request previously scheduled through a call to {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()", "requestAnimationFrame()")}}. + +Calling the `cancelAnimationFrame()` method requires the current worker to have an associated owner {{domxref("Window", "window")}}. That means that the current worker must be created by {{domxref("Window", "window")}} or by a dedicated worker that also has an associated owner {{domxref("Window", "window")}}. + +## Syntax + +```js-nolint +cancelAnimationFrame(handle) +``` + +### Parameters + +- `handle` + - : The ID value returned by a call to {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()", "requestAnimationFrame()")}}; the call must have been made in the same worker. + +### Return value + +None ({{jsxref("undefined")}}). + +### Exceptions + +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the method is not supported by the current worker. + +## Examples + +On the main thread, we start by transferring the control of a {{HTMLElement("canvas")}} element to an {{domxref("OffscreenCanvas")}}, using {{domxref("HTMLCanvasElement.transferControlToOffscreen()")}} and send to a message to `"start"` its work to the worker, with the offscreen canvas: + +```js +const offscreenCanvas = document + .querySelector("canvas") + .transferControlToOffscreen(); + +worker.postMessage( + { + type: "start", + canvas: offscreenCanvas, + }, + [offscreenCanvas], +); +``` + +When receiving the `"start"` message, the worker starts the animation, moving the rectangle from left to right. Upon reception of a `"stop"` message, it will stop the animation. + +```js +let ctx; +let pos = 0; + +function draw(dt) { + ctx.clearRect(0, 0, 100, 100); + ctx.fillRect(pos, 0, 10, 10); + pos += 10 * dt; + self.requestAnimationFrame(draw); +} + +self.addEventListener("message", (e) => { + if (e.data.type === "start") { + const transferredCanvas = e.data.canvas; + ctx = transferredCanvas.getContext("2d"); + self.requestAnimationFrame(draw); + } + if (e.data.type === "stop") { + self.cancelAnimationFrame(handle); + } +}); +``` + +Finally, if needed, the main thread can send a `"stop"` message to the worker to stop the animation: + +```js +worker.postMessage({ + type: "stop", +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()")}} +- {{domxref("Window.cancelAnimationFrame()")}} diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/index.md index 5676f01e516c7a6..6de9b466728b244 100644 --- a/files/en-us/web/api/dedicatedworkerglobalscope/index.md +++ b/files/en-us/web/api/dedicatedworkerglobalscope/index.md @@ -26,6 +26,10 @@ _This interface inherits methods from the {{domxref("WorkerGlobalScope")}} inter - : Discards any tasks queued in the `WorkerGlobalScope`'s event loop, effectively closing this particular scope. - {{domxref("DedicatedWorkerGlobalScope.postMessage()")}} - : Sends a message — which can consist of `any` JavaScript object — to the parent document that first spawned the worker. +- {{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()")}} + - : Cancels an animation frame request previously scheduled through a call to {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()", "requestAnimationFrame()")}}. +- {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()")}} + - : Perform an animation frame request and call a user-supplied callback function before the next repaint. ## Events diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/requestanimationframe/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/requestanimationframe/index.md new file mode 100644 index 000000000000000..7c99d7175c19053 --- /dev/null +++ b/files/en-us/web/api/dedicatedworkerglobalscope/requestanimationframe/index.md @@ -0,0 +1,108 @@ +--- +title: "DedicatedWorkerGlobalScope: requestAnimationFrame() method" +short-title: requestAnimationFrame() +slug: Web/API/DedicatedWorkerGlobalScope/requestAnimationFrame +page-type: web-api-instance-method +browser-compat: api.DedicatedWorkerGlobalScope.requestAnimationFrame +--- + +{{APIRef}} + +The **`requestAnimationFrame()`** method of the {{domxref("DedicatedWorkerGlobalScope")}} interface tells the browser you wish to perform an animation frame request and call a user-supplied callback function before the next repaint. + +The frequency of calls to the callback function will generally match the display refresh rate. The most common refresh rate is 60 Hz, (60 cycles/frames per second), though 75 Hz, 120 Hz, and 144 Hz are also widely used. `requestAnimationFrame()` calls are paused in most browsers when running in background tabs or hidden {{HTMLElement("iframe")}}s, to improve performance and battery life. + +A call to the `requestAnimationFrame()` method schedules only one single call to the callback function. If you want to animate another frame, your callback function must call `requestAnimationFrame()` again. + +> **Warning:** Be sure always to use the first argument (or some other method for getting the current time) to calculate how much the animation will progress in a frame — **otherwise, the animation will run faster on high refresh-rate screens**. For ways to do that, see the examples below. + +Calling the `requestAnimationFrame()` method requires the current worker to have an associated owner {{domxref("Window", "window")}}. That means that the current worker must be created by {{domxref("Window", "window")}} or by a dedicated worker that also has an associated owner {{domxref("Window", "window")}}. + +## Syntax + +```js-nolint +requestAnimationFrame(callback) +``` + +### Parameters + +- `callback` + - The function to call when it's time to update your animation for the next repaint. This callback function is passed a single argument: a {{domxref("DOMHighResTimeStamp")}} indicating the end time of the previous frame's rendering (based on the number of milliseconds since [time origin](/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)). + - The timestamp is a decimal number, in milliseconds, but with a minimal precision of 1 millisecond. The timestamp value is also similar to calling {{domxref('performance.now()')}} at the start of the callback function, but it is never the same value. + - When multiple callbacks queued by `requestAnimationFrame()` begin to fire in a single frame, each receives the same timestamp even though time has passed during the computation of every previous callback's workload. + +### Return value + +A `long` integer value that is the request ID uniquely identifying the entry +in the callback list. This is a non-zero value, but you may not make any other +assumptions about it. You can pass this value to +{{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()", "cancelAnimationFrame()")}} to cancel the refresh callback request, the cancel action must have been made in the same worker. + +### Exceptions + +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the method is not supported by the current worker. + +## Examples + +On the main thread, we start by transferring the control of a {{HTMLElement("canvas")}} element to an {{domxref("OffscreenCanvas")}}, using {{domxref("HTMLCanvasElement.transferControlToOffscreen()")}}, then send a message to the worker to `"start"` its work with the offscreen canvas: + +```js +const offscreenCanvas = document + .querySelector("canvas") + .transferControlToOffscreen(); + +worker.postMessage( + { + type: "start", + canvas: offscreenCanvas, + }, + [offscreenCanvas], +); +``` + +When receiving the `"start"` message, the worker starts the animation, moving the rectangle from left to right. Upon reception of a `"stop"` message, it will stop the animation. + +```js +let ctx; +let pos = 0; + +function draw(dt) { + ctx.clearRect(0, 0, 100, 100); + ctx.fillRect(pos, 0, 10, 10); + pos += 10 * dt; + self.requestAnimationFrame(draw); +} + +self.addEventListener("message", (e) => { + if (e.data.type === "start") { + const transferredCanvas = e.data.canvas; + ctx = transferredCanvas.getContext("2d"); + self.requestAnimationFrame(draw); + } + if (e.data.type === "stop") { + self.cancelAnimationFrame(handle); + } +}); +``` + +Finally, if needed, the main thread can send a `"stop"` message to the worker to stop the animation: + +```js +worker.postMessage({ + type: "stop", +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()")}} +- {{domxref("Window.requestAnimationFrame()")}} diff --git a/files/en-us/web/api/window/cancelanimationframe/index.md b/files/en-us/web/api/window/cancelanimationframe/index.md index 74e49fdd6139adb..d0ac8c381a7575a 100644 --- a/files/en-us/web/api/window/cancelanimationframe/index.md +++ b/files/en-us/web/api/window/cancelanimationframe/index.md @@ -67,4 +67,5 @@ cancelAnimationFrame(myReq); ## See also -- {{domxref("window.requestAnimationFrame()")}} +- {{domxref("Window.requestAnimationFrame()")}} +- {{domxref("DedicatedWorkerGlobalScope.cancelAnimationFrame()")}} diff --git a/files/en-us/web/api/window/requestanimationframe/index.md b/files/en-us/web/api/window/requestanimationframe/index.md index 7e2534a9be24d25..730ba7a6e8e48f6 100644 --- a/files/en-us/web/api/window/requestanimationframe/index.md +++ b/files/en-us/web/api/window/requestanimationframe/index.md @@ -172,8 +172,7 @@ function animate() { ## See also - {{domxref("Window.cancelAnimationFrame()")}} -- {{domxref("OffscreenCanvas")}} -- [DedicatedWorkerGlobalScope](/en-US/docs/Web/API/DedicatedWorkerGlobalScope) +- {{domxref("DedicatedWorkerGlobalScope.requestAnimationFrame()")}} - [requestAnimationFrame for smart animating](https://www.paulirish.com/2011/requestanimationframe-for-smart-animating/) - Blog post - [Animating with JavaScript: from setInterval to requestAnimationFrame](https://hacks.mozilla.org/2011/08/animating-with-javascript-from-setinterval-to-requestanimationframe/) - Blog post - [TestUFO: Test your web browser for requestAnimationFrame() Timing Deviations](https://www.testufo.com/#test=animation-time-graph)