fragment-tools 0.1.0

package/docs/guide/exports.md

@@ -0,0 +1,86 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → Exports</sup>
+<br>
+
+# Exports
+
+`fragment` provides different ways to export sketches, whereas it's for communication or archive purposes. It currently supports image, video and live exports.
+
+Settings of the `Exports` module are saved in localStorage so they will be kept between working sessions as long as `fragment` starts on the same URL/port.
+
+## Export an image
+
+`fragment` can export .png, .webp and .jpeg files.
+
+You can change `encoding`, `quality` and `pixelsPerInch` in the module settings.
+
+The size of the image used when exporting will be the current one used for display. If you want to create hi-res exports, make sure to change the `dimensions` or `pixelRatio` of the canvas before doing so.
+
+> ⚠️ `pixelsPerInch` doesn't actually changed the resolution of the final exports, it only changes file metadata so it doesn't appear as a 72dpi file when opened in other softwares.
+
+If you need to export a sketch for impression, set `canvasSize` in Params to `preset`. Select the size you want in the new `preset` dropdown and set `pixelsPerInch` to `300` before exporting.
+
+Type `Cmd+S` on Mac or `Ctrl+S` on Windows to save a screenshot with selected settings into your working folder.
+
+## Export a video
+
+`fragment` can export .mp4, .gif, .webm videos and frame sequences.
+
+You can change the `framerate`, the `encoding` and the `quality` of the recording in the module settings.
+
+If `useDuration` is `true` and a sketch exports a [duration](../api/sketch.md#duration) property, the recording will stop once `fragment` has exported enough frames to compose the recording at specified framerate. This can be useful to export loop-based sketchs.
+
+If `loopCount` is greater than 1, the recording will stop once fragment has enough frames to compose the recording for a final duration equals to sketchDuration*loopCount. This can be useful to export loop-based sketchs with variations between loops.
+
+> ⚠️ The `framerate` used for recording can be different from sketch [fps](../api/sketch.md#duration) property.
+
+## Export a live version
+
+A sketch can be built into static files (html, js, css) to be deployed anywhere online.
+
+```
+fragment ./sketch.js --build
+```
+
+The static build can be configured from the sketch file by exporting a `buildConfig` object.
+
+```js
+export let buildConfig = {
+  backgroundColor: "red",
+  dimensions: [256, 256],
+  gui: {
+    position: "float",
+    align: "left",
+    size: 0.4,
+    output: false,
+	},
+  styles: /* css */`
+    :root {
+      --color-active: red;
+    }
+
+    canvas {
+      box-shadow: 0px 2px 12px -2px rgba(0, 0, 0, 0.35);
+    }
+  }`
+};
+```
+
+| name | type | effect | default |
+|---|---|---|---|
+| `backgroundColor` | `string` | Change the background color when canvas is not full size | `inherit` |
+| `dimensions` | `number[2]` | Change the dimensions of the canvas | Viewport size |
+| `canvasSize`| `string` | Change the resizing method of the canvas. Can be `window`, `fixed`, `scale`, `preset`, `aspect-ratio` | `window` |
+| `pixelRatio` | `number\|function` | Change the pixel ratio of the canvas. | `1` |
+| `gui` | `bool` | Display gui | `false` |
+| `gui.position` | `string` | Change gui appearance. Can be `fixed` or `float` | `float` |
+| `gui.align` | `string` | Change gui position. Can be `left` or `right` | `right` |
+| `gui.size` | `string\|number` | Change gui width. Can be a percentage or a number between 0 and 1 | `0.3`
+| `gui.output` | `string\|number` | Display canvasSize and dimensions fields in gui | `false` |
+| `gui.hidden` | `boolean` | Hide gui on start | `false` |
+| `styles` | `string` | Inject styles in document | `false` |
+
+A built sketch can be previewed on dev mode by typing `p`.
+
+## Change the filename
+
+By default, `fragment` will use the sketch filename and a timestamp to name your export like `sketch.js.2022.05.27-08.30.00.[extension]`. See [filenamePattern](../api/sketch.md#filenamepattern) to change this behavior.

package/docs/guide/external-dependencies.md

@@ -0,0 +1,22 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → External dependencies</sup>
+<br>
+
+# External dependencies
+
+You can manage dependencies of your project like you would do on a traditional `npm` project, [vite](https://vitejs.dev/) will bundle them on the fly on the first render of your sketch.
+
+## Example 
+
+```
+# Install a package from npmjs.com
+npm install my-project-dependency
+```
+
+```js
+// sketch.js
+import dependency from "my-project-dependency";
+
+export let init = () => {
+	// use `dependency` here
+};
+```

package/docs/guide/getting-started.md

@@ -0,0 +1,113 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → Getting started</sup>
+<br>
+
+# Getting started
+
+## Create a sketch
+
+In your terminal, type the following command to create a new sketch based on the 2D template.
+```
+fragment ./sketch.js --new --template=2d
+```
+Check [Templates docs](../api/CLI.md#templates) to see which templates are also available.
+
+Open `sketch.js` recently created in your favorite code editor. The file should looks like this:
+
+```js
+export let props = {};
+
+export let init = ({ context, width, height }) => {
+
+};
+
+export let update = ({ context, width, height, time, deltaTime }) => {
+  context.clearRect(0, 0, width, height);
+};
+
+export let resize = ({ width, height }) => {
+
+};
+
+export let rendering = "2d";
+```
+
+## Draw a circle
+
+Let's start by drawing a centered circle on the canvas. Because we used the `2d` template, the `update` function exposes a `context` param, which can be used to draw. See [CanvasRenderingContext2D docs](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) if you want to know more about what can be done with `context`.
+
+```js
+export let update = ({ context, width, height }) => {
+  // set the fill color to black
+  context.fillStyle = '#000000';
+  // draw a rectangle covering the entire canvas
+  context.fillRect(0, 0, width, height);
+
+  // choose a radius for your canvas
+  const radius = 20;
+
+  // change the fill color to blue
+  context.fillStyle = '#0000ff';
+  // draw the circle
+  context.beginPath();
+  context.arc(width * 0.5, height * 0.5, radius, 0, 2 * Math.PI, false);
+  // fill the previous path drawing with the current fillStyle
+  context.fill(); 
+};
+```
+
+## Create a GUI
+
+In order to quickly create controls on the screen, `fragment` checks for an existing `props` object exported from your sketch. The controls will be built based on the type of values in the `props` object.
+
+Let's create our first prop `radius`. 
+
+```js
+export let props = {
+  radius: {
+    value: 20,
+  }
+};
+
+export let update = () => {
+	// draw background
+  context.fillStyle = '#000000';
+  context.fillRect(0, 0, width, height);
+
+  const radius = props.radius.value; // get value from props object available in the scope
+
+  context.fillStyle = '#0000ff';
+  context.beginPath();
+  context.arc(width * 0.5, height * 0.5, radius, 0, 2 * Math.PI, false);
+  context.fill();
+}
+```
+
+You should see a new input field under `Parameters` labelled `radius`. Try changing the value, the canvas will redraw according to your new value. That's great but it's not ideal to manually enter a new value each time.
+
+Each `prop` can have a special property `params`. If the `[propName].value` is a `number`, then `params` can accept three new properties `min`, `max` and `step`.
+
+Let's add them:
+```js
+export let props = {
+  radius: {
+    value: 20,
+    params: {
+      min: 1,
+      max: 200,
+      step: 1,
+    }
+  }
+};
+```
+
+A slider should have appeared after saving the sketch file next to the previous input. Now if you click and drag on the slider, you should see your circle changing live.
+
+Congrats, you made your first sketch in `fragment`! 
+
+If you want to know more about `props` and what can be done with it, check out the [SketchProps](../api/sketch.md#sketchprops) section of the documentation.
+
+
+## Next steps
+
+- [Using triggers](./using-triggers.md)
+- [Exporting a sketch](./exports.md)

package/docs/guide/hot-shader-reloading.md

@@ -0,0 +1,20 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → Hot shader reloading</sup>
+<br>
+
+# Hot shader reloading
+
+Instead of using built-in HMR features of [vite](https://vitejs.dev/), `fragment` has its own way of reloading shaders when it encounters files with the following extensions:
+- `.glsl`
+- `.fs`
+- `.vs`
+- `.vert`
+- `.frag`
+
+## With `rendering="three"`
+
+When using [three.js](https://threejs.org/) rendering, `fragment` will traverse the `scene` provided in the params to see if the file recently saved has a filepath that matches a `fragmentShader` or `vertexShader` provided to a `ShaderMaterial` or a `RawShaderMaterial`.
+If you're using your own `Scene` instance, `fragment` will not be able to retrieve the materials currently in use and will reload the whole sketch instead.
+
+## With `rendering="fragment"`
+
+The single WebGLProgram displayed is recompiled on the fly.

package/docs/guide/shortcuts.md

@@ -0,0 +1,12 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → Shortcuts</sup>
+
+# Shortcuts
+
+| shortcut | action |
+|---|---|
+|`Cmd/Ctrl + S`| Capture canvas
+|`Cmd/Ctrl + Shift + S`| Record canvas
+|`r`| Reload sketch
+|`w`| Modify layout
+|`Space`| Pause rendering
+|`p`| Toggle Preview mode

package/docs/guide/using-triggers.md

@@ -0,0 +1,39 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → Using triggers</sup>
+
+# Using triggers
+
+Triggers are functions you can call imperatively from your sketch file to make it *interactive*. They can also be assigned on a prop through the UI.
+
+## From a sketch
+
+Instead of setting up the listener manually:
+```js
+export let init = ({ canvas }) => {
+    canvas.addEventListener('click', (event) => {
+		console.log("canvas clicked");
+	});
+}
+```
+
+You can import and use them in your sketch:
+```js
+import { onClick } from "@fragment/triggers";
+
+export let init = ({ canvas }) => {
+	onClick((event) => {
+		console.log("canvas clicked");
+	});
+}
+```
+
+See [Triggers API docs](../api/triggers.md) for usage.
+
+## From the UI
+
+Triggers can also added on specific type of fields from the UI, by clicking on the label of a field. Triggers can only be added when the type of a prop is a `function` or a number with `params: { min, max }`.
+
+They are saved in localStorage so they persist between refreshs. This is useful when you want to quickly test or prototype values.
+
+![Screen capture of Fragment, displaying a "color" field with the triggers UI opened and 3 triggers (onMouseDown, onKeyDown and onNoteOn setted](https://github.com/raphaelameaume/fragment/raw/main/docs/guide/triggers.png?raw=true "Screen Capture of Fragment UI for triggers")
+
+The dot on the left shows if a trigger is active or not. You can toggle activity by clicking on it.

package/examples/cube-three.js

@@ -0,0 +1,34 @@
+
+import * as THREE from "three";
+
+
+let camera;
+let mesh;
+
+export let init = ({ scene, width, height }) => {
+    camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
+    camera.position.z = 3;
+    camera.lookAt(new THREE.Vector3());
+
+	mesh = new THREE.Mesh(
+		new THREE.BoxBufferGeometry(1, 1, 1),
+		new THREE.MeshBasicMaterial({
+			color: 0xFF0000,
+			wireframe: true,
+		})
+	)
+
+	scene.add(mesh);
+};
+
+export let update = ({ renderer, scene, time, deltaTime }) => {
+	mesh.rotation.y += 0.01;
+    renderer.render(scene, camera);
+};
+
+export let resize = ({ width, height }) => {
+    camera.aspect = width / height;
+    camera.updateProjectionMatrix();
+};
+
+export let rendering = "three";

package/examples/ellipse-p5.js

@@ -0,0 +1,26 @@
+import p5 from "p5";
+
+export let props = {
+	radius: {
+		value: 100,
+		params: {
+			min: 10,
+			max: 200,
+			step: 1,
+		}
+	},
+};
+
+export let fps = 0;
+
+export let setup = ({ p, width, height }) => {};
+
+export let draw = ({ p, width, height }) => {
+	p.background(255, 0, 0);
+
+	const radius = props.radius.value;
+
+	p.ellipse(width * 0.5, height * 0.5, radius, radius);
+};
+
+export let rendering = "p5";

package/examples/icon.fs

@@ -0,0 +1,96 @@
+#version 300 es
+
+precision highp float;
+
+uniform float uTime;
+uniform vec2 uResolution;
+uniform float uRadius;
+uniform float uShift;
+
+in vec2 vUv;
+out vec4 FragColor;
+
+float aastep(float threshold, float value) {
+//   #ifdef GL_OES_standard_derivatives
+    float afwidth = length(vec2(dFdx(value), dFdy(value))) * 0.70710678118654757;
+    return smoothstep(threshold-afwidth, threshold+afwidth, value);
+//   #else
+//     return step(threshold, value);
+//   #endif  
+}
+
+float disc(vec2 st, float radius) {
+    return 1. - aastep(radius, length(st - vec2(0.5)));
+}
+
+float disc(vec2 st, float radius, vec2 center) {
+    return 1. - aastep(radius, length(st - center));
+}
+
+void main() {
+    float gridFactor = 40.;
+
+    float borderRadius = uRadius;
+    float c = 0.;
+    c += disc(vUv, borderRadius, vec2(1. - borderRadius, 1. - borderRadius));
+    c += disc(vUv, borderRadius, vec2(borderRadius, 1. - borderRadius));
+    c += disc(vUv, borderRadius, vec2(borderRadius, borderRadius));
+    c += disc(vUv, borderRadius, vec2(1. - borderRadius, borderRadius));
+
+    float q = 0.;
+    float qv = min(step(borderRadius, vUv.x), step(vUv.x, 1. - borderRadius));
+    float qh = min(step(borderRadius, vUv.y), step(vUv.y, 1. - borderRadius));
+
+    q = max(qh, qv);
+    q = clamp(q, 0., 1.);
+    c += q; 
+    c = clamp(c, 0., 1.);
+
+    float t = 1.;
+
+    vec3 color = vec3(0.);
+
+    vec2 grid = vUv * 41.;
+    vec2 uvp = fract(grid);
+
+    float colIndex = floor(grid.x);
+    float rowIndex = floor(grid.y);
+    float pattern = 0.;
+
+    float c1 = mod(colIndex, 2.) > 0. ? 1. : 0.;
+    float c2 = mod(colIndex + 1., 2.) > 0. ? 1. : 0.;
+    float r1 = mod(rowIndex, 2.) > 0. ? 1. : 0.;
+    float r2 = mod(rowIndex + 1., 2.) > 0. ? 1. : 0.;
+    
+    pattern = r1 * c1;
+    pattern += c2 * r2;
+    pattern = 1. - pattern;
+    
+    float gradient = 1. - mod(floor(vUv.x * (gridFactor * 2. + 1.)), 2.) > 0. ? 0. : 1.;
+
+    vec2 p0 = vec2(0.5);
+    vec2 p1 = p0 + (1. / (gridFactor * 2. + 1.)) * 7. * t;
+    vec2 p2 = p0 - (1. / (gridFactor * 2. + 1.)) * 7. * t;
+
+    float r = (1. / gridFactor * 10.) * t;
+
+    float ra1 = disc(vUv, r, p2);
+    float ra2 = disc(vUv, r, p0);
+    float ra3 = disc(vUv, r, p1);
+
+    ra1 *= gradient;
+    ra2 *= (1. - gradient);
+    ra3 *= gradient;
+
+    pattern *= 1. - c;
+    pattern += 0.9 * (1. - c);
+
+    color += vec3(1., 0., 0.) * ra1;
+    color += vec3(0., 1., 0.) * ra2;
+    color += vec3(0., 0., 1.) * ra3;
+
+    float alpha = 1.;
+    alpha *= c;
+
+    FragColor = vec4(color, alpha);
+}

package/examples/icon.js

@@ -0,0 +1,63 @@
+import fragmentShader from "./icon.fs";
+
+
+export let props = {
+	radius: {
+		value: 0.1,
+		params: {
+			min: 0,
+			max: 0.5,
+			step: 0.01,
+		}
+	},
+	shift: {
+		value: 0.05,
+		params: {
+			min: 0,
+			max: 1,
+			step: 0.001,
+		}
+	},
+	progress: {
+		value: 0,
+		params: {
+			min: 0,
+			max: 1,
+			step: 0.001,
+		}
+	},
+};
+
+let uniforms = {
+	uTime: { value: 0, type: "float" },
+	uRadius: { value: props.radius.value, type: "float" },
+	uShift: { value: props.shift.value, type: "float" },
+};
+
+export let fps = 0;
+
+export let init = ({ frag }) => {
+	frag.uniforms = uniforms;
+	frag.shader = fragmentShader;
+	frag.vertexShader = `#version 300 es
+in vec4 position;
+in vec2 uv;
+
+out vec2 vUv;
+
+void main(){
+	vUv = uv;
+	gl_Position = position;
+}
+`;
+};
+
+export let update = ({ frag, deltaTime }) => {
+	uniforms.uTime.value += deltaTime;
+	uniforms.uRadius.value = props.radius.value;
+	uniforms.uShift.value = props.shift.value;
+
+	frag.render();
+};
+
+export let rendering = "fragment";

package/examples/package-lock.json

@@ -0,0 +1,40 @@
+{
+  "name": "fragment-examples",
+  "version": "1.0.0",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "fragment-examples",
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "p5": "^1.4.1",
+        "three": "^0.140.2"
+      },
+      "devDependencies": {}
+    },
+    "node_modules/p5": {
+      "version": "1.4.2",
+      "resolved": "https://registry.npmjs.org/p5/-/p5-1.4.2.tgz",
+      "integrity": "sha512-J5zqZ/l1NIbJSuNr/FH9nDYgBRg7/NubStNPnx1fQCMSAgxI6peKDHs9i5iaG9EuwbJzjuG6/5bX/D0lqqrP9A=="
+    },
+    "node_modules/three": {
+      "version": "0.140.2",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.140.2.tgz",
+      "integrity": "sha512-DdT/AHm/TbZXEhQKQpGt5/iSgBrmXpjU26FNtj1KhllVPTKj1eG4X/ShyD5W2fngE+I1s1wa4ttC4C3oCJt7Ag=="
+    }
+  },
+  "dependencies": {
+    "p5": {
+      "version": "1.4.2",
+      "resolved": "https://registry.npmjs.org/p5/-/p5-1.4.2.tgz",
+      "integrity": "sha512-J5zqZ/l1NIbJSuNr/FH9nDYgBRg7/NubStNPnx1fQCMSAgxI6peKDHs9i5iaG9EuwbJzjuG6/5bX/D0lqqrP9A=="
+    },
+    "three": {
+      "version": "0.140.2",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.140.2.tgz",
+      "integrity": "sha512-DdT/AHm/TbZXEhQKQpGt5/iSgBrmXpjU26FNtj1KhllVPTKj1eG4X/ShyD5W2fngE+I1s1wa4ttC4C3oCJt7Ag=="
+    }
+  }
+}

package/examples/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "fragment-examples",
+  "version": "1.0.0",
+  "description": "",
+  "dependencies": {
+    "p5": "^1.4.1",
+    "three": "^0.140.2"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "start": "fragment ./circle-2d.js"
+  },
+  "author": "Raphaël Améaume",
+  "license": "MIT"
+}

package/examples/shape-2d.js

@@ -0,0 +1,45 @@
+export let props = {
+  background: {
+    value: "#0057B8",
+  },
+  fill: {
+    value: "#FFD700",
+  },
+  size: {
+    value: 256,
+    params: {
+      min: 64,
+      max: 512
+    },
+  },
+  shape: {
+    value: "circle",
+    params: {
+      options: ["circle", "square"]
+    }
+  },
+};
+
+export let fps = 0;
+
+export let update = ({ context, width, height }) => {
+  // draw background
+  context.fillStyle = props.background.value;
+  context.fillRect(0, 0, width, height);
+
+  // draw circle
+  const shape = props.shape.value;
+  const size = props.size.value;
+
+  context.fillStyle = props.fill.value;
+
+  if (shape === "circle") {
+    context.beginPath();
+    context.arc(width * 0.5, height * 0.5, size, 0, 2 * Math.PI, false);
+    context.fill();
+  } else if (shape === "square") {
+    context.fillRect(width * 0.5 - size, height * 0.5 - size, size * 2, size * 2);
+  }
+};
+
+export let rendering = "2d";

package/examples/shape-three.js

@@ -0,0 +1,49 @@
+
+import * as THREE from "three";
+
+import fragmentShader from "./shape-tree.fs";
+
+let camera;
+let mesh;
+
+export let init = ({ scene, width, height }) => {
+    camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
+    camera.position.z = 3;
+    camera.lookAt(new THREE.Vector3());
+
+	mesh = new THREE.Mesh(
+		new THREE.PlaneBufferGeometry(1, 1),
+		new THREE.ShaderMaterial({
+			vertexShader: `
+void main() {
+	gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.);
+}
+			`,
+			fragmentShader:
+			`
+void main() {
+	gl_FragColor = vec4(0., 1., 0., 1.);
+}
+			`,
+			wireframe: true,
+		}),
+		// new THREE.MeshBasicMaterial({
+		// 	color: 0xFF0000,
+		// 	wireframe: true,
+		// })
+	);
+
+	scene.add(mesh);
+};
+
+export let update = ({ renderer, scene, time, deltaTime }) => {
+	mesh.rotation.y += 0.01;
+    renderer.render(scene, camera);
+};
+
+export let resize = ({ width, height }) => {
+    camera.aspect = width / height;
+    camera.updateProjectionMatrix();
+};
+
+export let rendering = "three";

package/examples/shape-tree.fs

@@ -0,0 +1,3 @@
+void main() {
+	gl_FragColor = vec4(1., 1., 0., 1.);
+}