├── .gitignore
├── screenshot.gif
├── .npmignore
├── .editorconfig
├── types.js
├── LICENSE.md
├── package.json
├── index.js
├── CHANGELOG.md
├── index.html
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .DS_Store
3 | /types
4 | /lib
5 | 


--------------------------------------------------------------------------------
/screenshot.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/dmnsgn/canvas-context/HEAD/screenshot.gif


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
 1 | /web_modules
 2 | /examples
 3 | /docs
 4 | /coverage
 5 | /test
 6 | /.github
 7 | screenshot.*
 8 | index.html
 9 | tsconfig.json
10 | .editorconfig
11 | .nojekyll
12 | 


--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
 1 | root = true
 2 | 
 3 | [*]
 4 | end_of_line = lf
 5 | charset = utf-8
 6 | indent_style = space
 7 | indent_size = 2
 8 | trim_trailing_whitespace = true
 9 | insert_final_newline = true
10 | 


--------------------------------------------------------------------------------
/types.js:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * @typedef {"2d" | "webgl" | "experimental-webgl" | "webgl2" | "webgl2-compute" | "bitmaprenderer" | "gpupresent" | "webgpu"} ContextType A DOMString containing the context identifier defining the drawing context associated to the canvas.
 3 |  */
 4 | 
 5 | /**
 6 |  * @typedef {object} CanvasContextOptions Options for canvas creation. All optional.
 7 |  * @property {number} [width=300] Request an initial canvas width.
 8 |  * @property {number} [height=150] Request an initial canvas height.
 9 |  * @property {boolean} [offscreen=false] Request an offscreen canvas.
10 |  * @property {boolean} [worker=false] Handle use in a worker.
11 |  * @property {CanvasRenderingContext2DSettings | WebGLContextAttributes} [contextAttributes={}] Attributes to be passed to getContext.
12 |  * @property {HTMLCanvasElement} [canvas=undefined] Canvas element to use.
13 |  */
14 | 
15 | /**
16 |  * @typedef {object} CanvasContextReturnValue
17 |  * @property {HTMLCanvasElement | OffscreenCanvas} canvas
18 |  * @property {RenderingContext} context
19 |  */
20 | 
21 | export {};
22 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | Copyright (C) 2019 Damien Seguin
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in
11 | all copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19 | THE SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "canvas-context",
 3 |   "version": "3.3.1",
 4 |   "description": "Create a RenderingContext (2d, webgl, webgl2, bitmaprenderer, webgpu), optionally offscreen for possible use in a Worker.",
 5 |   "keywords": [
 6 |     "canvas",
 7 |     "context",
 8 |     "offscreen",
 9 |     "worker",
10 |     "offscreen-canvas",
11 |     "2d",
12 |     "webgl",
13 |     "experimental-webgl",
14 |     "webgl2",
15 |     "bitmaprenderer",
16 |     "webgpu",
17 |     "gpupresent"
18 |   ],
19 |   "homepage": "https://github.com/dmnsgn/canvas-context",
20 |   "bugs": "https://github.com/dmnsgn/canvas-context/issues",
21 |   "repository": {
22 |     "type": "git",
23 |     "url": "git+https://github.com/dmnsgn/canvas-context.git"
24 |   },
25 |   "funding": [
26 |     {
27 |       "type": "individual",
28 |       "url": "https://paypal.me/dmnsgn"
29 |     },
30 |     {
31 |       "type": "individual",
32 |       "url": "https://commerce.coinbase.com/checkout/56cbdf28-e323-48d8-9c98-7019e72c97f3"
33 |     }
34 |   ],
35 |   "license": "MIT",
36 |   "author": "Damien Seguin (https://github.com/dmnsgn)",
37 |   "sideEffects": false,
38 |   "type": "module",
39 |   "exports": {
40 |     ".": {
41 |       "types": "./types/index.d.ts",
42 |       "default": "./index.js"
43 |     }
44 |   },
45 |   "main": "index.js",
46 |   "types": "types/index.d.ts",
47 |   "engines": {
48 |     "node": ">=22.0.0",
49 |     "npm": ">=10.5.1",
50 |     "snowdev": ">=2.2.x"
51 |   }
52 | }
53 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
 1 | /** @module createCanvasContext */
 2 | 
 3 | const contextTypeList = [
 4 |   "2d",
 5 |   "webgl",
 6 |   "experimental-webgl",
 7 |   "webgl2",
 8 |   "webgl2-compute",
 9 |   "bitmaprenderer",
10 |   "gpupresent",
11 |   "webgpu",
12 | ];
13 | 
14 | /**
15 |  * Create a RenderingContext (2d, webgl, webgl2, bitmaprenderer, webgpu), optionally offscreen for possible use in a Worker.
16 |  *
17 |  * @alias module:createCanvasContext
18 |  * @param {import("./types.js").ContextType} [contextType="2d"]
19 |  * @param {import("./types.js").CanvasContextOptions} [options={}]
20 |  * @returns {import("./types.js").CanvasContextReturnValue}
21 |  */
22 | function createCanvasContext(contextType = "2d", options = {}) {
23 |   // Get options and set defaults
24 |   const {
25 |     width,
26 |     height,
27 |     offscreen = false,
28 |     worker = false,
29 |     contextAttributes = {},
30 |   } = {
31 |     ...options,
32 |   };
33 | 
34 |   // Check contextType is valid
35 |   if (!worker && !contextTypeList.includes(contextType)) {
36 |     throw new TypeError(`Unknown contextType: "${contextType}"`);
37 |   }
38 | 
39 |   // Return in Node or in a Worker unless a canvas is provided
40 |   // See https://github.com/Automattic/node-canvas for an example
41 |   if (typeof window === "undefined" && !options.canvas) {
42 |     return null;
43 |   }
44 | 
45 |   // Get offscreen canvas if requested and available
46 |   const canvasEl = options.canvas || document.createElement("canvas");
47 |   const canvas =
48 |     (offscreen || worker) && "OffscreenCanvas" in window
49 |       ? canvasEl.transferControlToOffscreen()
50 |       : canvasEl;
51 | 
52 |   // Set canvas dimensions (default to 300 in browsers)
53 |   if (Number.isInteger(width) && width >= 0) canvas.width = width;
54 |   if (Number.isInteger(height) && height >= 0) canvas.height = height;
55 | 
56 |   if (worker) return { canvas };
57 | 
58 |   // Get the context with specified attributes and handle experimental-webgl
59 |   let context;
60 |   try {
61 |     context =
62 |       canvas.getContext(contextType, contextAttributes) ||
63 |       (contextType === "webgl"
64 |         ? canvas.getContext("experimental-webgl", contextAttributes)
65 |         : null);
66 |   } catch (error) {
67 |     console.error(error);
68 |     context = null;
69 |   }
70 | 
71 |   return {
72 |     canvas,
73 |     context,
74 |   };
75 | }
76 | 
77 | export default createCanvasContext;
78 | 
79 | export * from "./types.js";
80 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | 
 3 | All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 4 | 
 5 | ## [3.3.1](https://github.com/dmnsgn/canvas-context/compare/v3.3.0...v3.3.1) (2025-09-15)
 6 | 
 7 | 
 8 | ### Bug Fixes
 9 | 
10 | * add canvas to CanvasContextOptions ([082e203](https://github.com/dmnsgn/canvas-context/commit/082e203eb7e29f932a2a3995bd63884a85f338a5))
11 | 
12 | 
13 | 
14 | # [3.3.0](https://github.com/dmnsgn/canvas-context/compare/v3.2.0...v3.3.0) (2024-07-06)
15 | 
16 | 
17 | ### Features
18 | 
19 | * log error on getContext failure ([66ee6e1](https://github.com/dmnsgn/canvas-context/commit/66ee6e163cd637463d9e98109a12e93523dec170))
20 | 
21 | 
22 | 
23 | # [3.2.0](https://github.com/dmnsgn/canvas-context/compare/v3.1.0...v3.2.0) (2022-04-02)
24 | 
25 | 
26 | ### Features
27 | 
28 | * replace gpupresent with webgpu ([42a6dc7](https://github.com/dmnsgn/canvas-context/commit/42a6dc72a6e64801095eb92d846674aa29411e4e))
29 | 
30 | 
31 | 
32 | # [3.1.0](https://github.com/dmnsgn/canvas-context/compare/v3.0.2...v3.1.0) (2021-10-02)
33 | 
34 | 
35 | ### Features
36 | 
37 | * add exports field to package.json ([1237509](https://github.com/dmnsgn/canvas-context/commit/12375095edb87e72dcde45600652707ffcf4492a))
38 | 
39 | 
40 | 
41 | ## [3.0.2](https://github.com/dmnsgn/canvas-context/compare/v3.0.1...v3.0.2) (2021-04-14)
42 | 
43 | 
44 | ### Bug Fixes
45 | 
46 | * export types ([99c61bd](https://github.com/dmnsgn/canvas-context/commit/99c61bdf267b01410fd449f10c68b69196b412ed))
47 | 
48 | 
49 | 
50 | ## [3.0.1](https://github.com/dmnsgn/canvas-context/compare/v3.0.0...v3.0.1) (2021-03-22)
51 | 
52 | 
53 | ### Bug Fixes
54 | 
55 | * add sideEffects key to package.json ([5a0110e](https://github.com/dmnsgn/canvas-context/commit/5a0110ed66fa12ccd9b1961e6b0a185dd26b1b6e))
56 | 
57 | 
58 | 
59 | ## [3.0.0](https://github.com/dmnsgn/canvas-context/compare/v2.0.0...v3.0.0) (2021-03-18)
60 | 
61 | 
62 | ### ⚠ BREAKING CHANGES
63 | 
64 | * use ES modules
65 | 
66 | ### Bug Fixes
67 | 
68 | * update README ([28db6a6](https://github.com/dmnsgn/canvas-context/commit/28db6a692311a097934191cd3d12f781fc393a64))
69 | * update README ([d2dd3b2](https://github.com/dmnsgn/canvas-context/commit/d2dd3b29e4973e79ec6c2a042d24a2f1dfe293d1))
70 | 
71 | 
72 | * use ES modules ([b88a047](https://github.com/dmnsgn/canvas-context/commit/b88a047350c678c7536e096a91124da43a185a94))
73 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 |   <head>
  4 |     <meta charset="UTF-8" />
  5 |     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  6 |     <meta http-equiv="X-UA-Compatible" content="ie=edge" />
  7 |     <title>canvas-context by Damien Seguin (https://github.com/dmnsgn)</title>
  8 |     <style>
  9 |       :root {
 10 |         --color-dark: #404040;
 11 |         --color-light: #f2f2f2;
 12 |         --color-accent: #fd5e62;
 13 |       }
 14 | 
 15 |       body {
 16 |         margin: 0;
 17 |         overscroll-behavior: none;
 18 |         font-family: sans-serif;
 19 |         color: var(--color-dark);
 20 |         background-color: var(--color-light);
 21 |       }
 22 | 
 23 |       main {
 24 |         padding: 0 20px;
 25 |       }
 26 |     </style>
 27 |   </head>
 28 |   <body>
 29 |     <main>
 30 |       <h1>canvas-context</h1>
 31 |       <h2>Window context</h2>
 32 |       <canvas id="canvas-window" width="100" height="100"></canvas>
 33 | 
 34 |       <h2>Worker context</h2>
 35 |       <canvas id="canvas-worker" width="100" height="100"></canvas>
 36 |       <br />
 37 |       <button id="button">Block the main thread</button>
 38 |     </main>
 39 | 
 40 |     <script type="module">
 41 |       import createCanvasContext from "./index.js";
 42 | 
 43 |       // Store an animation function to evaluate later in both the window and worker
 44 | 
 45 |       const TEST_FUNCTION = /* js */ `
 46 | const loop = () => {
 47 |   const now = Date.now() * 0.005;
 48 | 
 49 |   // Clear
 50 |   context.clearRect(0, 0, context.canvas.width, context.canvas.height);
 51 | 
 52 |   // Draw
 53 |   context.save();
 54 |   context.translate(50, 50);
 55 |   context.beginPath();
 56 |   context.arc(0, 0, 25 - Math.cos(now) * 10, 0, 2 * Math.PI);
 57 |   context.fillStyle = "${window
 58 |     .getComputedStyle(document.documentElement)
 59 |     .getPropertyValue("--color-accent")}";
 60 |   context.fill();
 61 |   context.restore();
 62 | 
 63 |   requestAnimationFrame(loop);
 64 | };
 65 | loop();
 66 | `;
 67 | 
 68 |       // Create a usual context in Window
 69 |       const { context } = createCanvasContext("2d", {
 70 |         canvas: document.querySelector("#canvas-window"),
 71 |         offscreen: true,
 72 |       });
 73 | 
 74 |       new Function(["context"], TEST_FUNCTION)(context);
 75 | 
 76 |       // Use a Worker
 77 |       const packageUrl = new URL("./index.js", import.meta.url).href;
 78 |       const blob = new Blob(
 79 |         [
 80 |           /* js */ `
 81 | import createCanvasContext from "${packageUrl}";
 82 | 
 83 | addEventListener("message", ({ data }) => {
 84 |   if (data.msg == "canvas-context-init") {
 85 |     const { context } = createCanvasContext("2d", {
 86 |       canvas: data.canvas,
 87 |     });
 88 |     ${TEST_FUNCTION}
 89 |   }
 90 | });
 91 |       `,
 92 |         ],
 93 |         { type: "text/javascript" }
 94 |       );
 95 |       const worker = new Worker(URL.createObjectURL(blob), { type: "module" });
 96 | 
 97 |       // Worker can't transfer a canvas context so passing worker will only return an OffscreenCanvas
 98 |       const { canvas: offscreenCanvas } = createCanvasContext(null, {
 99 |         canvas: document.querySelector("#canvas-worker"),
100 |         worker: true,
101 |       });
102 | 
103 |       worker.postMessage(
104 |         { msg: "canvas-context-init", canvas: offscreenCanvas },
105 |         [offscreenCanvas]
106 |       );
107 | 
108 |       // Simulate a thread blocking action
109 |       function blockThread(milliseconds) {
110 |         const start = new Date().getTime();
111 |         for (var i = 0; i < 1e7; i++) {
112 |           if (new Date().getTime() - start > milliseconds) {
113 |             break;
114 |           }
115 |         }
116 |       }
117 | 
118 |       document.querySelector("#button").addEventListener("click", () => {
119 |         requestAnimationFrame(() => {
120 |           blockThread(2500);
121 |         });
122 |       });
123 |     </script>
124 |   </body>
125 | </html>
126 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # canvas-context
  2 | 
  3 | [![npm version](https://img.shields.io/npm/v/canvas-context)](https://www.npmjs.com/package/canvas-context)
  4 | [![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)](https://www.npmjs.com/package/canvas-context)
  5 | [![npm minzipped size](https://img.shields.io/bundlephobia/minzip/canvas-context)](https://bundlephobia.com/package/canvas-context)
  6 | [![dependencies](https://img.shields.io/librariesio/release/npm/canvas-context)](https://github.com/dmnsgn/canvas-context/blob/master/package.json)
  7 | [![types](https://img.shields.io/npm/types/canvas-context)](https://github.com/microsoft/TypeScript)
  8 | [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg)](https://conventionalcommits.org)
  9 | [![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://github.com/prettier/prettier)
 10 | [![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://github.com/eslint/eslint)
 11 | [![license](https://img.shields.io/github/license/dmnsgn/canvas-context)](https://github.com/dmnsgn/canvas-context/blob/master/LICENSE)
 12 | 
 13 | Create a RenderingContext (2d, webgl, webgl2, bitmaprenderer, webgpu), optionally offscreen for possible use in a Worker.
 14 | 
 15 | [![paypal](https://img.shields.io/badge/donate-paypal-informational?logo=paypal)](https://paypal.me/dmnsgn)
 16 | [![coinbase](https://img.shields.io/badge/donate-coinbase-informational?logo=coinbase)](https://commerce.coinbase.com/checkout/56cbdf28-e323-48d8-9c98-7019e72c97f3)
 17 | [![twitter](https://img.shields.io/twitter/follow/dmnsgn?style=social)](https://twitter.com/dmnsgn)
 18 | 
 19 | ![](https://raw.githubusercontent.com/dmnsgn/canvas-context/master/screenshot.gif)
 20 | 
 21 | See the [example](https://dmnsgn.github.io/canvas-context/) and its [source](index.html) with a Worker implementation.
 22 | 
 23 | ## Installation
 24 | 
 25 | ```bash
 26 | npm install canvas-context
 27 | ```
 28 | 
 29 | ## Usage
 30 | 
 31 | ```js
 32 | import createCanvasContext from "canvas-context";
 33 | 
 34 | const { context, canvas } = createCanvasContext("2d", {
 35 |   width: 100,
 36 |   height: 100,
 37 |   offscreen: true,
 38 | });
 39 | ```
 40 | 
 41 | ## API
 42 | 
 43 | <!-- api-start -->
 44 | 
 45 | ## Modules
 46 | 
 47 | <dl>
 48 | <dt><a href="#module_createCanvasContext">createCanvasContext</a></dt>
 49 | <dd></dd>
 50 | </dl>
 51 | 
 52 | ## Typedefs
 53 | 
 54 | <dl>
 55 | <dt><a href="#ContextType">ContextType</a> : <code>&quot;2d&quot;</code> | <code>&quot;webgl&quot;</code> | <code>&quot;experimental-webgl&quot;</code> | <code>&quot;webgl2&quot;</code> | <code>&quot;webgl2-compute&quot;</code> | <code>&quot;bitmaprenderer&quot;</code> | <code>&quot;gpupresent&quot;</code> | <code>&quot;webgpu&quot;</code></dt>
 56 | <dd><p>A DOMString containing the context identifier defining the drawing context associated to the canvas.</p>
 57 | </dd>
 58 | <dt><a href="#CanvasContextOptions">CanvasContextOptions</a> : <code>object</code></dt>
 59 | <dd><p>Options for canvas creation. All optional.</p>
 60 | </dd>
 61 | <dt><a href="#CanvasContextReturnValue">CanvasContextReturnValue</a> : <code>object</code></dt>
 62 | <dd></dd>
 63 | </dl>
 64 | 
 65 | <a name="module_createCanvasContext"></a>
 66 | 
 67 | ## createCanvasContext
 68 | 
 69 | <a name="exp_module_createCanvasContext--createCanvasContext"></a>
 70 | 
 71 | ### createCanvasContext([contextType], [options]) ⇒ [<code>CanvasContextReturnValue</code>](#CanvasContextReturnValue) ⏏
 72 | 
 73 | Create a RenderingContext (2d, webgl, webgl2, bitmaprenderer, webgpu), optionally offscreen for possible use in a Worker.
 74 | 
 75 | **Kind**: Exported function
 76 | 
 77 | | Param         | Type                                                       | Default                     |
 78 | | ------------- | ---------------------------------------------------------- | --------------------------- |
 79 | | [contextType] | [<code>ContextType</code>](#ContextType)                   | <code>&quot;2d&quot;</code> |
 80 | | [options]     | [<code>CanvasContextOptions</code>](#CanvasContextOptions) | <code>{}</code>             |
 81 | 
 82 | <a name="ContextType"></a>
 83 | 
 84 | ## ContextType : <code>&quot;2d&quot;</code> \| <code>&quot;webgl&quot;</code> \| <code>&quot;experimental-webgl&quot;</code> \| <code>&quot;webgl2&quot;</code> \| <code>&quot;webgl2-compute&quot;</code> \| <code>&quot;bitmaprenderer&quot;</code> \| <code>&quot;gpupresent&quot;</code> \| <code>&quot;webgpu&quot;</code>
 85 | 
 86 | A DOMString containing the context identifier defining the drawing context associated to the canvas.
 87 | 
 88 | **Kind**: global typedef
 89 | <a name="CanvasContextOptions"></a>
 90 | 
 91 | ## CanvasContextOptions : <code>object</code>
 92 | 
 93 | Options for canvas creation. All optional.
 94 | 
 95 | **Kind**: global typedef
 96 | **Properties**
 97 | 
 98 | | Name                | Type                                                                                 | Default            | Description                            |
 99 | | ------------------- | ------------------------------------------------------------------------------------ | ------------------ | -------------------------------------- |
100 | | [width]             | <code>number</code>                                                                  | <code>300</code>   | Request an initial canvas width.       |
101 | | [height]            | <code>number</code>                                                                  | <code>150</code>   | Request an initial canvas height.      |
102 | | [offscreen]         | <code>boolean</code>                                                                 | <code>false</code> | Request an offscreen canvas.           |
103 | | [worker]            | <code>boolean</code>                                                                 | <code>false</code> | Handle use in a worker.                |
104 | | [contextAttributes] | <code>CanvasRenderingContext2DSettings</code> \| <code>WebGLContextAttributes</code> | <code>{}</code>    | Attributes to be passed to getContext. |
105 | | [canvas]            | <code>HTMLCanvasElement</code>                                                       |                    | Canvas element to use.                 |
106 | 
107 | <a name="CanvasContextReturnValue"></a>
108 | 
109 | ## CanvasContextReturnValue : <code>object</code>
110 | 
111 | **Kind**: global typedef
112 | **Properties**
113 | 
114 | | Name    | Type                                                           |
115 | | ------- | -------------------------------------------------------------- |
116 | | canvas  | <code>HTMLCanvasElement</code> \| <code>OffscreenCanvas</code> |
117 | | context | <code>RenderingContext</code>                                  |
118 | 
119 | <!-- api-end -->
120 | 
121 | ## License
122 | 
123 | MIT. See [license file](LICENSE.md).
124 | 


--------------------------------------------------------------------------------