@shaderfrog/core 0.0.2 → 0.1.0

package/README.md

@@ -1,3 +1,186 @@
 # Shaderfrog Core
 
-Experimental. Do not use this.
+🚨 This library is experimental! 🚨
+🚨 The API can change at any time! 🚨
+
+The core graph API that powers Shaderfrog. This API, built on top of the
+[@Shaderfrog/glsl-parser](https://github.com/ShaderFrog/glsl-parser), compiles
+Shaderfrog graphs into an intermediate result, which you then pass off to an
+_engine_ (aka a plugin), to create a running GLSL shader.
+
+### Graph
+
+```typescript
+interface Graph {
+  nodes: GraphNode[];
+  edges: Edge[];
+}
+```
+
+The Shaderfrog _graph_ is a list of nodes and edges. It represents all of the
+GLSL code and configurations in your material. Conceptually, a graph is similar
+to a dependency graph for source code, where edges represent relationships
+(including dependencies) between nodes.
+
+Each _node_ in the graph is some type of GLSL (raw source code) and configuration.
+Some graph node GLSL is hard coded, as in written by you, like in a
+`SourceNode`. Some source code is generated at runtime by an engine, and
+injected into a node right before the graph is compiled.
+
+Each _edge_ in the graph represents a dependency between two nodes. Edges have
+different types and meanings, based on which inputs and outputs they're
+connected to.
+
+The main API function for working with graphs are `compileGraph` and
+`computeGraphContext`:
+
+```typescript
+type compileGraph = (
+  engineContext: EngineContext,
+  engine: Engine,
+  graph: Graph
+): CompileGraphResult
+
+type computeGraphContext = async (
+  engineContext: EngineContext,
+  engine: Engine,
+  graph: Graph
+): void
+```
+
+A graph's _context_, more specifically a node's context, is the runtime /
+in-memory computed data associated with a graph node. It includes the parsed AST
+representation of the node, as well as the inputs found in that AST.
+
+### Parsers
+
+A graph is a vanilla Javscript object. To convert it to context, there's one
+"parser" per node type in the graph, defined in the engine configuration. A
+parser is an object with this interface:
+
+```typescript
+type NodeParser = {
+  // cacheKey?: (graph: Graph, node: GraphNode, sibling?: GraphNode) => string;
+  // Callback hook to manipulate the node right before it's compiled by the
+  // graph. Engines use this to dynamically generate node source code.
+  onBeforeCompile?: OnBeforeCompile;
+  // Callback hook to manipulate the parsed AST. Example use is to convert
+  // standalone GLSL programs into code that can be used in the graph, like
+  // turning `void main() { out = color; }` into `vec4 main() { return color; }`
+  manipulateAst?: ManipulateAst;
+  // Find the inputs for this node type. Done dynamically because it's based on
+  // the source code of the node.
+  findInputs?: FindInputs;
+  // Create the filler AST offered up to nodes that import this node.
+  produceFiller?: ProduceNodeFiller;
+};
+```
+
+### Engine
+
+Shaderfrog is a GLSL editor. It's not a Three.js editor, nor a Babylon.js
+editor, etc. The output of Shaderfrog is raw GLSL and metadata.
+
+To use shaders in your _engine_, like Three.js, or even your own home grown
+engine, you implement your engine as a _plugin_ to Shaderfrog. An engine
+definition is verbose and likely to change:
+
+```typescript
+export interface Engine {
+  // The name of your engine, like "three"
+  name: string;
+  // Which GLSL variables are defined in your engine's materials
+  preserve: Set<string>;
+  // Rules for how to merge source code from different nodes together
+  mergeOptions: MergeOptions;
+  // Parsers for your engine node types. These are combined with the
+  // core engine parsers
+  parsers: Record<string, NodeParser>;
+  // Functions to import graphs/code from other engines into your own
+  importers: EngineImporters;
+  // How to evaluate a node, like turning a node of { type: 'vec3' } into a
+  // THREE.Vector3
+  evaluateNode: (node: DataNode) => any;
+  // How to create specific nodes in your engine
+  constructors: {
+    [EngineNodeType]: NodeConstructor;
+  };
+}
+```
+
+### Inputs, Holes and Fillers
+
+Shaderfrog works by searching each node's AST for certain patterns, like
+`uniform` variables, and creating an interface where you can replace each
+`uniform` variable with the output of another node. 
+
+Each fillable part of the AST is called a __hole__. Holes are found by executing
+user defined _strategies_ against an AST. With a program such as:
+
+```glsl
+uniform vec2 uv;
+void main() {
+  vec2 someVar = uv * 2.0;
+}
+```
+
+If you apply the `uniform` strategy to this code, it will mark the AST nodes
+relevant to the uniform as _holes_:
+
+```glsl
+uniform vec2 [uv];
+void main() {
+  vec2 someVar = [uv] * 2.0;
+}
+```
+
+And it adds a new _input_ to your node, named `uv` in this case.
+
+When you plug in the output of another node into this input, it _"fills in"_ the
+hole with the _filler_ output of another node. A _filler_ is an AST node. For
+example, if you have another node like:
+
+```glsl
+vec2 myFn() {
+  return vec2(1.0, 1.0);
+}
+```
+
+And you plug in the `myFn` output into the `uv` input, the hole is _filled_,
+resulting in:
+
+```glsl
+vec2 myFn() {
+  return vec2(1.0, 1.0);
+}
+
+void main() {
+  vec2 someVar = myFn() * 2.0;
+}
+```
+
+Note that this is not a simple find and replace. Not only was the `uv` variable
+replaced, but the declaration line `uniform vec2 uv;` was removed, and `myFn`
+was inlined into the final program.
+
+Hole filling always produces a new AST, or more accurately, a new
+`ShaderSections`, which is the intermediary representation of the compilation
+process.
+
+### Static Monkeypatching
+
+This whole process allows Shaderfrog to monkeypatch engine shaders. When
+modifying an engine shader, the process is:
+
+- Shaderfrog creates a `BABYLON.PBRMaterial` or `Three.MeshPhysicalMaterial` (or
+  whatever built in material type you want)
+- Shaderfrog reads the engine material's generated GLSL, and then modifies it to
+  add new effects by injecting new GLSL
+- Shaderfrog dumps the new compiled GLSL back into the `BABYLON.PBRMaterial` or
+  `Three.MeshPhysicalMaterial`, and updates the material to add a new uniforms.
+
+Injecting new GLSL into an engine shader is essentially _monkeypatching_ it:
+your code is modifying an external library's code. I call this _static
+monkeypatching_ because compiles new source code. This is opposed to traditional
+monkeypatching in languages like Ruby, where you modify external modules by
+changing them at runtime.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@shaderfrog/core",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Shaderfrog core",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "prepare": "npm run build",
+    "build": "./build.sh",
+    "watch-test": "jest --watch",
+    "test": "jest --colors"
   },
   "repository": {
     "type": "git",
@@ -13,7 +16,7 @@
   "author": "Andrew Ray",
   "license": "ISC",
   "files": [
-    "src"
+    "dist"
   ],
   "bugs": {
     "url": "https://github.com/ShaderFrog/core/issues"
@@ -37,8 +40,10 @@
     "lodash.groupby": "^4.6.0"
   },
   "peerDependencies": {
+    "@shaderfrog/glsl-parser": "^2.0.0-beta.5",
     "babylonjs": ">=4",
-    "three": ">=0.50"
+    "three": ">=0.50",
+    "playcanvas": "^1.65.3"
   },
   "peerDependenciesMeta": {
     "babylonjs": {
@@ -46,6 +51,9 @@
     },
     "three": {
       "optional": true
+    },
+    "playcanvas": {
+      "optional": true
     }
   }
 }

package/src/ast/manipulate.ts

@@ -1,392 +0,0 @@
-/**
- * Utility functions to work with ASTs
- */
-import { parser, generate } from '@shaderfrog/glsl-parser';
-import {
-  visit,
-  AstNode,
-  NodeVisitors,
-  ExpressionStatementNode,
-  FunctionNode,
-  AssignmentNode,
-  DeclarationStatementNode,
-  KeywordNode,
-  DeclarationNode,
-} from '@shaderfrog/glsl-parser/ast';
-import { Program } from '@shaderfrog/glsl-parser/ast';
-import { ShaderStage } from '../core/graph';
-
-export const findVec4Constructor = (ast: AstNode): AstNode | undefined => {
-  let parent: AstNode | undefined;
-  const visitors: NodeVisitors = {
-    function_call: {
-      enter: (path) => {
-        if (
-          'specifier' in path.node.identifier &&
-          path.node.identifier?.specifier?.token === 'vec4'
-        ) {
-          parent = path.findParent((p) => 'right' in p.node)?.node;
-          path.skip();
-        }
-      },
-    },
-  };
-  visit(ast, visitors);
-  return parent;
-};
-
-export const findAssignmentTo = (
-  ast: AstNode | Program,
-  assignTo: string
-): ExpressionStatementNode | undefined => {
-  let assign: ExpressionStatementNode | undefined;
-  const visitors: NodeVisitors = {
-    expression_statement: {
-      enter: (path) => {
-        if (path.node.expression?.left?.identifier === assignTo) {
-          assign = path.node;
-        }
-        path.skip();
-      },
-    },
-  };
-  visit(ast, visitors);
-  return assign;
-};
-
-export const findDeclarationOf = (
-  ast: AstNode | Program,
-  declarationOf: string
-): DeclarationNode | undefined => {
-  let declaration: DeclarationNode | undefined;
-  const visitors: NodeVisitors = {
-    declaration_statement: {
-      enter: (path) => {
-        const foundDecl = path.node.declaration?.declarations?.find(
-          (decl: any) => decl?.identifier?.identifier === declarationOf
-        );
-        if (foundDecl) {
-          declaration = foundDecl;
-        }
-        path.skip();
-      },
-    },
-  };
-  visit(ast, visitors);
-  return declaration;
-};
-
-export const from2To3 = (ast: Program, stage: ShaderStage) => {
-  const glOut = 'fragmentColor';
-  // TODO: add this back in when there's only one after the merge
-  // ast.program.unshift({
-  //   type: 'preprocessor',
-  //   line: '#version 300 es',
-  //   _: '\n',
-  // });
-  if (stage === 'fragment') {
-    ast.program.unshift({
-      type: 'declaration_statement',
-      declaration: {
-        type: 'declarator_list',
-        specified_type: {
-          type: 'fully_specified_type',
-          qualifiers: [{ type: 'keyword', token: 'out', whitespace: ' ' }],
-          specifier: {
-            type: 'type_specifier',
-            specifier: { type: 'keyword', token: 'vec4', whitespace: ' ' },
-            quantifier: null,
-          },
-        },
-        declarations: [
-          {
-            type: 'declaration',
-            identifier: {
-              type: 'identifier',
-              identifier: glOut,
-              whitespace: undefined,
-            },
-            quantifier: null,
-            operator: undefined,
-            initializer: undefined,
-          },
-        ],
-        commas: [],
-      },
-      semi: { type: 'literal', literal: ';', whitespace: '\n    ' },
-    });
-  }
-  visit(ast, {
-    function_call: {
-      enter: (path) => {
-        const identifier = path.node.identifier;
-        if (
-          'specifier' in identifier &&
-          identifier.specifier?.identifier === 'texture2D'
-        ) {
-          identifier.specifier.identifier = 'texture';
-        }
-      },
-    },
-    identifier: {
-      enter: (path) => {
-        if (path.node.identifier === 'gl_FragColor') {
-          path.node.identifier = glOut;
-        }
-      },
-    },
-    keyword: {
-      enter: (path) => {
-        if (
-          (path.node.token === 'attribute' || path.node.token === 'varying') &&
-          path.findParent((path) => path.node.type === 'declaration_statement')
-        ) {
-          path.node.token =
-            stage === 'vertex' && path.node.token === 'varying' ? 'out' : 'in';
-        }
-      },
-    },
-  });
-};
-
-export const outDeclaration = (name: string): Object => ({
-  type: 'declaration_statement',
-  declaration: {
-    type: 'declarator_list',
-    specified_type: {
-      type: 'fully_specified_type',
-      qualifiers: [{ type: 'keyword', token: 'out', whitespace: ' ' }],
-      specifier: {
-        type: 'type_specifier',
-        specifier: { type: 'keyword', token: 'vec4', whitespace: ' ' },
-        quantifier: null,
-      },
-    },
-    declarations: [
-      {
-        type: 'declaration',
-        identifier: {
-          type: 'identifier',
-          identifier: name,
-          whitespace: undefined,
-        },
-        quantifier: null,
-        operator: undefined,
-        initializer: undefined,
-      },
-    ],
-    commas: [],
-  },
-  semi: { type: 'literal', literal: ';', whitespace: '\n    ' },
-});
-
-export const makeStatement = (stmt: string): AstNode => {
-  // console.log(stmt);
-  let ast;
-  try {
-    ast = parser.parse(
-      `${stmt};
-`,
-      { quiet: true }
-    );
-  } catch (error: any) {
-    console.error({ stmt, error });
-    throw new Error(`Error parsing stmt "${stmt}": ${error?.message}`);
-  }
-  // console.log(util.inspect(ast, false, null, true));
-  return ast.program[0];
-};
-
-export const makeFnStatement = (fnStmt: string): AstNode => {
-  let ast;
-  try {
-    ast = parser.parse(
-      `
-  void main() {
-      ${fnStmt};
-    }`,
-      { quiet: true }
-    );
-  } catch (error: any) {
-    console.error({ fnStmt, error });
-    throw new Error(`Error parsing fnStmt "${fnStmt}": ${error?.message}`);
-  }
-
-  // console.log(util.inspect(ast, false, null, true));
-  return (ast.program[0] as FunctionNode).body.statements[0];
-};
-
-export const makeExpression = (expr: string): AstNode => {
-  let ast;
-  try {
-    ast = parser.parse(
-      `void main() {
-          a = ${expr};
-        }`,
-      { quiet: true }
-    );
-  } catch (error: any) {
-    console.error({ expr, error });
-    throw new Error(`Error parsing expr "${expr}": ${error?.message}`);
-  }
-
-  // console.log(util.inspect(ast, false, null, true));
-  return (ast.program[0] as FunctionNode).body.statements[0].expression.right;
-};
-
-export const makeExpressionWithScopes = (expr: string): Program => {
-  let ast: Program;
-  try {
-    ast = parser.parse(
-      `void main() {
-          ${expr};
-        }`,
-      { quiet: true }
-    );
-  } catch (error: any) {
-    console.error({ expr, error });
-    throw new Error(`Error parsing expr "${expr}": ${error?.message}`);
-  }
-
-  // console.log(util.inspect(ast, false, null, true));
-  return {
-    type: 'program',
-    // Set the main() fn body scope as the global one
-    scopes: [ast.scopes[1]],
-    program: [(ast.program[0] as FunctionNode).body.statements[0].expression],
-  };
-};
-
-export const findFn = (ast: Program, name: string): FunctionNode | undefined =>
-  ast.program.find(
-    (stmt): stmt is FunctionNode =>
-      stmt.type === 'function' && stmt.prototype.header.name.identifier === name
-  );
-
-export const returnGlPosition = (fnName: string, ast: Program): void =>
-  convertVertexMain(fnName, ast, 'vec4', (assign) => assign.expression.right);
-
-export const returnGlPositionHardCoded = (
-  fnName: string,
-  ast: Program,
-  returnType: string,
-  hardCodedReturn: string
-): void =>
-  convertVertexMain(fnName, ast, returnType, () =>
-    makeExpression(hardCodedReturn)
-  );
-
-export const returnGlPositionVec3Right = (fnName: string, ast: Program): void =>
-  convertVertexMain(fnName, ast, 'vec3', (assign) => {
-    let found: AstNode | undefined;
-    visit(assign, {
-      function_call: {
-        enter: (path) => {
-          const { node } = path;
-          if (
-            // @ts-ignore
-            node?.identifier?.specifier?.token === 'vec4' &&
-            node?.args?.[2]?.token?.includes('1.')
-          ) {
-            found = node.args[0];
-          }
-        },
-      },
-    });
-    if (!found) {
-      console.error(generate(ast));
-      throw new Error(
-        'Could not find position assignment to convert to return!'
-      );
-    }
-    return found;
-  });
-
-const convertVertexMain = (
-  fnName: string,
-  ast: Program,
-  returnType: string,
-  generateRight: (positionAssign: ExpressionStatementNode) => AstNode
-) => {
-  const mainReturnVar = `frogOut`;
-
-  const main = findFn(ast, fnName);
-  if (!main) {
-    throw new Error(`No ${fnName} fn found!`);
-  }
-
-  // Convert the main function to one that returns
-  (main.prototype.header.returnType.specifier.specifier as KeywordNode).token =
-    returnType;
-
-  // Find the gl_position assignment line
-  const assign = main.body.statements.find(
-    (stmt: AstNode) =>
-      stmt.type === 'expression_statement' &&
-      stmt.expression.left?.identifier === 'gl_Position'
-  );
-  if (!assign) {
-    throw new Error(`No gl position assign found in main fn!`);
-  }
-
-  const rtnStmt = makeFnStatement(
-    `${returnType} ${mainReturnVar} = 1.0`
-  ) as DeclarationStatementNode;
-  rtnStmt.declaration.declarations[0].initializer = generateRight(assign);
-
-  main.body.statements.splice(main.body.statements.indexOf(assign), 1, rtnStmt);
-  main.body.statements.push(makeFnStatement(`return ${mainReturnVar}`));
-};
-
-export const convert300MainToReturn = (fnName: string, ast: Program): void => {
-  const mainReturnVar = `frogOut`;
-
-  // Find the output variable, as in "pc_fragColor" from  "out highp vec4 pc_fragColor;"
-  let outName: string | undefined;
-  ast.program.find((line, index) => {
-    if (
-      line.type === 'declaration_statement' &&
-      line.declaration?.specified_type?.qualifiers?.find(
-        (n: KeywordNode) => n.token === 'out'
-      ) &&
-      line.declaration.specified_type.specifier.specifier.token === 'vec4'
-    ) {
-      // Remove the out declaration
-      ast.program.splice(index, 1);
-      outName = line.declaration.declarations[0].identifier.identifier;
-      return true;
-    }
-  });
-  if (!outName) {
-    console.error(generate(ast));
-    throw new Error('No "out vec4" line found in the fragment shader');
-  }
-
-  visit(ast, {
-    identifier: {
-      enter: (path) => {
-        if (path.node.identifier === outName) {
-          path.node.identifier = mainReturnVar;
-          // @ts-ignore
-          path.node.doNotDescope = true; // hack because this var is in the scope which gets renamed later
-        }
-      },
-    },
-    function: {
-      enter: (path) => {
-        if (path.node.prototype.header.name.identifier === fnName) {
-          (
-            path.node.prototype.header.returnType.specifier
-              .specifier as KeywordNode
-          ).token = 'vec4';
-          path.node.body.statements.unshift(
-            makeFnStatement(`vec4 ${mainReturnVar}`)
-          );
-          path.node.body.statements.push(
-            makeFnStatement(`return ${mainReturnVar}`)
-          );
-        }
-      },
-    },
-  });
-};