/mtw-boilerplate-graphics

Combo of esbuild, GLSLX, three.js... to develop/build quickly + easily WebGL canvas bundles. Minimized bundles can be used as 3D animated backgrounds on a website - Demo:

Primary LanguageJavaScriptMIT LicenseMIT

MTW-BOILERPLATE-GRAPHICS





Snyk Vulnerabilities
 pending...
Full Report: Last One


This boilerplate allows you to develop quickly and easily WebGL canvas bundles. It has two modes. The result of production mode is a minimized bundle. You can embed this bundle as a 3D animated background on a website, for example.

In development mode, the GLSLX shader files are watched. That means, if you edit them and save your changes, the shaders will be recompiled and reloaded immediately. Feel free to adapt the existing shaders or create a completely new one. If you need inspiration, check out Shadertoy or GLSL Sandbox for fragment shaders and Vertexshaderart for vertex shaders. There you can see what's possible.

If you don't need this boilerplate but would like to embed the already minimized canvas bundles directly on your website, see the following.


| Canvas Bundle Usage

Application Examples:

Header.mp4
Header.mp4
Header.mp4
Header.mp4

Embedding Examples:

with jsDelivr

<canvas id="mtw-canvas" style="width:100vw;height:100vh;left:0;top:0;position:fixed;"></canvas>
<script src="https://cdn.jsdelivr.net/gh/mythemeway/mtw-canvas-disks@0.0.2/boilerplate-canvas/twgl/canvas.bundle.min.js"></script>

self hosting

<canvas id="mtw-canvas" style="width:100vw;height:100vh;left:0;top:0;position:fixed;"></canvas>
<script src="./canvas.bundle.min.js"></script>

Warning: WebGL canvases can make your CPU sweat. For the environment, stop the requestAnimationFrame loop when the canvas isn't visible #GreenCoding. See my website-boilerplate for an example.

TWGL or three.js

Two types of minimized bundles are available for each canvas. One contains TWGL and one contains three.js instead. I recommend using the TWGL bundles because they are much smaller as you can see in the table below.

Bundle Sizes malachite __disks__ __spiral__ blacksea
TWGL  pending...  pending...  pending...  pending...
three.js  pending...  pending...  pending...  pending...

Note: Badges are clickable and linked to the corresponding minimized bundle.


| Feature Overview

Branch: main

Node.js esbuild three.js TWGL GLSLX prepr terser

Note:

Additional Feature Information:

[click to toggle]

Note: Cards are clickable and linked to the corresponding GitHub repositories.


| Setup

To enable local operation of this boilerplate, you can do the following:

  1. open your terminal and define your startup file MYSTARTUPFILE in use
    • e. g. for Zsh 
       MYSTARTUPFILE=".zshrc"
    • or for pure Bash 
       MYSTARTUPFILE=".bashrc" # or .bash_profile for macOS
  2. install nvm and source your startup file again 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
source ~/$MYSTARTUPFILE
  3. if your terminal has closed, open it again and continue
  4. execute nvm install --lts to install Node.js
  5. clone the repository git clone https://github.com/mythemeway/mtw-boilerplate-graphics or your fork to your local machine
  6. change your current directory to mtw-boilerplate-graphics cd mtw-boilerplate-graphics
  7. run npm install

Note: If you've already installed Node.js LTS you only have to do steps 5-7.

That's it.


| Boilerplate Usage

Run Development Mode

Go to the mtw-boilerplate-graphics directory on your local machine and execute npm start. The result will appear at e. g. http://localhost:8080.

Run Production Mode

There are two ways to get your minimized bundle.

Way 1: npm run build = without terser [default] [faster]

Way 2: npm run terser = with terser additionally [smaller]

Note: output directory is always ~/mtw-boilerplate-graphics/dist

Switch Canvas

  1. open ~/mtw-boilerplate-graphics/canvas.config.js
  2. change const canvas and save it 
    // 
// CANVAS SETTINGS
//  - path:  path to canvas
//  - prepr: GLSL preprocessing
//  - id:    canvas id attribute
// 

// TWGL
//
// const canvas = { path: './src/twgl/mtw-canvas-disks', prepr: null, id: 'mtw-canvas' };
// const canvas = { path: './src/twgl/mtw-canvas-malachite', prepr: {}, id: 'mtw-canvas' };
// const canvas = { path: './src/twgl/mtw-canvas-blacksea', prepr: {}, id: 'mtw-canvas' };
// const canvas = { path: './src/twgl/mtw-canvas-spiral', prepr: null, id: 'mtw-canvas' };

// three.js
// 
// const canvas = { path: './src/three/mtw-canvas-disks', prepr: null, id: 'mtw-canvas' };
const canvas = { path: './src/three/mtw-canvas-malachite', prepr: {}, id: 'mtw-canvas' };
// const canvas = { path: './src/three/mtw-canvas-blacksea', prepr: {}, id: 'mtw-canvas' };
// const canvas = { path: './src/three/mtw-canvas-spiral', prepr: null, id: 'mtw-canvas' };

module.exports = canvas;

Add Canvas

  1. put mtw-canvas-new into the ~/mtw-boilerplate-graphics/src/... directory
  2. follow the switch canvas procedure 
    // 
// CANVAS SETTINGS
//  - path:  path to canvas
//  - prepr: GLSL preprocessing
//  - id:    canvas id attribute
// 

// TWGL
//
// const canvas = { path: './src/twgl/mtw-canvas-disks', prepr: null, id: 'mtw-canvas' };
// const canvas = { path: './src/twgl/mtw-canvas-malachite', prepr: {}, id: 'mtw-canvas' };
const canvas = {
	path: './src/twgl/mtw-canvas-new',
	prepr: {
		myVar: 1,
		myMacro: function (arg) { return arg; }
	},
	id: 'mtw-canvas'
};
// const canvas = { path: './src/twgl/mtw-canvas-blacksea', prepr: {}, id: 'mtw-canvas' };
// const canvas = { path: './src/twgl/mtw-canvas-spiral', prepr: null, id: 'mtw-canvas' };

module.exports = canvas;

Note:

  • mtw-canvas-new must have a main.js file

  • your canvas id attribute setting is only used in production mode; in development mode it is always the default mtw-canvas

  • if you switch/add a canvas in development mode, the result is displayed immediately after saving your changes

  • to customize the fragment and/or vertex shaders, modify the shaders.glslx files

  • mtw-canvas-disks [included] [default]; Fragment shader is based on CoordSys - intersection [License: MIT; Copyright: © 2013 Inigo Quilez; Changes: made]

  • mtw-canvas-malachite [included]; Fragment shader is based on Glare of water [License: CC BY 3.0; Copyright: © 2019 Jan Mróz; Changes: made]

  • mtw-canvas-spiral and mtw-canvas-blacksea [not included]; you have to add them manually


| Other Boilerplates

| Appendix

Note on protected brand names and logos

  • The use of protected brand names, trade names, utility models and brand logos on this website does not constitute an infringement of copyright; rather, it serves as an illustrative note. Even if this is not marked as such at the respective points, the corresponding legal provisions always apply.

  • The brand names and logos used are the property of their respective owners and are subject to their copyright provisions.

  • This offer is in no way related to the legal entities of the protected brand names and logos used.

Note on liability for links

  • This README contains links to external third-party websites. The README operator has no influence on the content of these sites. Therefore, he cannot assume any liability. Instead, the respective provider is always responsible for the content.

  • The linked pages were checked for possible legal violations at the time of linking and illegal content wasn't discernible. A permanent control of the linked pages is unreasonable without concrete evidence of an infringement. However, if the README operator becomes aware of such a violation, he will act immediately.

Readme uses