shaderkit

Tools and IntelliSense for GLSL and WGSL.

Table of Contents

- Installation
- Tokenize
- Minify
- Parse
- Generate
- Visit
- AST
- Node Objects
- Identifier
- Literal
- ArraySpecifier
- Program
- Statements
- ExpressionStatement
- BlockStatement
- DiscardStatement
- PreprocessorStatement
- PrecisionQualifierStatement
- InvariantQualifierStatement
- LayoutQualifierStatement
- Control Flow
- ReturnStatement
- BreakStatement
- ContinueStatement
- Choice
- IfStatement
- SwitchStatement
- SwitchCase
- Loops
- WhileStatement
- DoWhileStatement
- ForStatement
- Declarations
- FunctionDeclaration
- FunctionParameter
- VariableDeclaration
- VariableDeclarator
- StructuredBufferDeclaration
- StructDeclaration
- Expressions
- ArrayExpression
- Unary Operations
- UnaryExpression
- UnaryOperator
- UpdateExpression
- UpdateOperator
- Binary Operations
- BinaryExpression
- BinaryOperator
- AssignmentExpression
- AssignmentOperator
- LogicalExpression
- LogicalOperator
- MemberExpression
- ConditionalExpression
- CallExpression

Installation

To install, use your preferred package manager:

``bash
npm install shaderkit
yarn add shaderkit
pnpm add shaderkit
`

Or, use a CDN:

`html

`

Tokenize

Tokenizes a string of GLSL or WGSL code, returning an array of Token objects, where each Token object represents a single syntax feature in the input code.

`ts
interface Token {
type: 'whitespace' | 'comment' | 'symbol' | 'bool' | 'float' | 'int' | 'identifier' | 'keyword'
value: string
}
`

The following are the supported token types and their descriptions:

| Type | Description |
| ---------- | ------------------------------------------------------------------------- |
| whitespace | A sequence of one or more whitespace characters. |
| comment | A single-line or multi-line comment. |
| symbol | A symbol, such as an operator or punctuation mark. |
| bool | A boolean value, either true or false. |
| float | A floating-point number, represented by a sequence of digits and symbols. |
| int | An integer number, represented by a sequence of digits. |
| identifier | A user-defined identifier, such as a variable name or function name. |
| keyword | A keyword reserved by the language, such as if, else, for, etc. |

Minify

Minifies a string of GLSL or WGSL code, returning a minified version of the input code.

`ts
const minified: string = minify(code: string, {
/* Whether to rename variables. Will call a MangleMatcher if specified. Default is false. /
mangle: boolean | ((token: Token, index: number, tokens: Token[]) => boolean)
/* A map to read and write renamed variables to when mangling. /
mangleMap: Map
/* Whether to rename external variables such as uniforms or varyings. Default is false. /
mangleExternals: boolean
})
`

To shared mangled interfaces when using mangleExternal, declare and re-use a mangleMap between shaders:

`ts
const options = { mangle: true, mangleExternals: true, mangleMap: new Map() }

// #version 300 es\nin vec2 a;out vec2 b;void main(){b=a;}
minify(#version 300 es\nin vec2 sstt;out vec2 c;void main(){c=sstt;}, options)

// #version 300 es\nin vec2 b;out vec4 a[gl_MaxDrawBuffers];void main(){a[0]=b.sstt;}
minify(#version 300 es\nin vec2 c;out vec4 data[gl_MaxDrawBuffers];void main(){data[0]=c.sstt;}, options)
`

Parse

Parses a string of GLSL (WGSL is WIP) code into an AST.

`ts
const ast: Program = parse(code: string)
`

Generate

Generates a string of GLSL (WGSL is WIP) code from an AST.

`ts
const code: string = generate(program: Program, {
target: 'GLSL' // | 'WGSL'
})
`

Visit

Recurses through an AST, calling a visitor object on matching nodes.

`ts
visit(
program: Program,
visitors: {
Program: {
enter(node, ancestors) {
// Called before any descendant nodes are processed
},
exit(node, ancestors) {
// Called after all nodes are processed
}
},
Identifier(node, ancestors) {
// Called before any descendant nodes are processed (alias to enter)
}
} satisfies Visitors
)
`

AST

An Abstract Syntax Tree loosely based on ESTree for GLSL and WGSL grammars.

$3

AST nodes extend Node objects which implement the following abstract interface:

`ts
interface Node {
type: string
}
`

The type field is a string representing the AST variant type which can determine the interface a node implements.

$3

A variable identifier.

`ts
interface Identifier extends Node {
type: 'Identifier'
name: string
}
`

$3

A shader literal representing a bool, float, int, or uint type.

`ts
interface Literal extends Node {
type: 'Literal'
value: string
}
`

$3

An array and its dimensions.

`ts
interface ArraySpecifier extends Node {
type: 'ArraySpecifier'
typeSpecifier: Identifier
dimensions: (Literal | Identifier | null)[]
}
`

$3

Represents the root of an AST.

`ts
interface Program extends Node {
type: 'Program'
body: Statement[]
}
`

$3

An expression as a standalone statement.

`ts
interface ExpressionStatement extends Node {
type: 'ExpressionStatement'
expression: Expression
}
`

$3

A block statement.

`ts
interface BlockStatement extends Node {
type: 'BlockStatement'
body: Statement[]
}
`

$3

A discard statement in fragment shaders.

`ts
interface DiscardStatement extends Node {
type: 'DiscardStatement'
}
`

$3

A GLSL preprocessor statement with an optional value.

`ts
interface PreprocessorStatement extends Node {
type: 'PreprocessorStatement'
name: string
value: Expression[] | null
}
`

$3

A GLSL precision qualifier statement.

`ts
interface PrecisionQualifierStatement extends Node {
type: 'PrecisionQualifierStatement'
precision: PrecisionQualifier
typeSpecifier: Identifier
}
`

$3

A GLSL invariant qualifier statement.

`ts
interface InvariantQualifierStatement extends Node {
type: 'InvariantQualifierStatement'
typeSpecifier: Identifier
}
`

$3

A layout qualifier statement.

`ts
interface LayoutQualifierStatement extends Node {
type: 'LayoutQualifierStatement'
layout: Record
qualifier: StorageQualifier
}
`

$3

A return statement with an optional argument.

`ts
interface ReturnStatement extends Node {
type: 'ReturnStatement'
argument: Expression | null
}
`

$3

A break statement.

`ts
interface BreakStatement extends Node {
type: 'BreakStatement'
}
`

$3

A continue statement.

`ts
interface ContinueStatement extends Node {
type: 'ContinueStatement'
}
`

$3

An if-else statement.

`ts
interface IfStatement extends Node {
type: 'IfStatement'
test: Expression
consequent: Statement
alternate: Statement | null
}
`

$3

A switch statement.

`ts
interface SwitchStatement extends Node {
type: 'SwitchStatement'
discriminant: Expression
cases: SwitchCase[]
}
`

#### SwitchCase

A switch-case statement. test is null for a default case.

`ts
interface SwitchCase extends Node {
type: 'SwitchCase'
test: Expression | null
consequent: Statement[]
}
`

$3

A while statement.

`ts
interface WhileStatement extends Node {
type: 'WhileStatement'
test: Expression
body: Statement
}
`

$3

A do-while statement.

`ts
interface DoWhileStatement extends Node {
type: 'DoWhileStatement'
body: Statement
test: Expression
}
`

$3

A for statement.

`ts
interface ForStatement extends Node {
type: 'ForStatement'
init: VariableDeclaration | Expression | null
test: Expression | null
update: Expression | null
body: Statement
}
`

$3

A function declaration. body is null for overloads.

`ts
interface FunctionDeclaration extends Node {
type: 'FunctionDeclaration'
id: Identifier
qualifiers: PrecisionQualifier[]
typeSpecifier: Identifier | ArraySpecifier
params: FunctionParameter[]
body: BlockStatement | null
}
`

#### FunctionParameter

A function parameter within a function declaration.

`ts
interface FunctionParameter extends Node {
type: 'FunctionParameter'
id: Identifier | null
qualifiers: (ConstantQualifier | ParameterQualifier | PrecisionQualifier)[]
typeSpecifier: Identifier | ArraySpecifier
}
`

$3

A variable declaration.

`ts
interface VariableDeclaration extends Node {
type: 'VariableDeclaration'
declarations: VariableDeclarator[]
}
`

#### VariableDeclarator

A variable declarator within a variable declaration.

`ts
interface VariableDeclarator extends Node {
type: 'VariableDeclarator'
id: Identifier
qualifiers: (ConstantQualifier | InterpolationQualifier | StorageQualifier | PrecisionQualifier)[]
typeSpecifier: Identifier | ArraySpecifier
layout: Record | null
init: Expression | null
}
`

$3

A buffer interface declaration with optional layout and qualifiers.

`ts
interface StructuredBufferDeclaration extends Node {
type: 'StructuredBufferDeclaration'
id: Identifier | null
qualifiers: (InterfaceStorageQualifier | MemoryQualifier | LayoutQualifier)[]
typeSpecifier: Identifier | ArraySpecifier
layout: Record | null
members: VariableDeclaration[]
}
`

$3

A struct declaration. Can be used as a type or constructor.

`ts
interface StructDeclaration extends Node {
type: 'StructDeclaration'
id: Identifier
members: VariableDeclaration[]
}
`

$3

An array initialization expression.

`ts
interface ArrayExpression extends Node {
type: 'ArrayExpression'
typeSpecifier: ArraySpecifier
elements: Expression[]
}
`

$3

A unary expression with a left or right handed operator.

`ts
interface UnaryExpression extends Node {
type: 'UnaryExpression'
operator: UnaryOperator
prefix: boolean
argument: Expression
}
`

#### UnaryOperator

`ts
type UnaryOperator = '-' | '+' | '!' | '~'
`

$3

An update expression with an optionally prefixed operator.

`ts
interface UpdateExpression extends Node {
type: 'UpdateExpression'
operator: UpdateOperator
argument: Expression
prefix: boolean
}
`

#### UpdateOperator

`ts
type UpdateOperator = '++' | '--'
`

$3

A binary expression with a left and right operand.

`ts
interface BinaryExpression extends Node {
type: 'BinaryExpression'
operator: BinaryOperator
left: Expression
right: Expression
}
`

#### BinaryOperator

`ts
type BinaryOperator =
| ','
| '=='
| '!='
| '<'
| '<='
| '>'
| '>='
| '<<'
| '>>'
| '+'
| '-'
| '*'
| '/'
| '%'
| '|'
| '^'
| '&'
`

$3

An assignment expression.

`ts
interface AssignmentExpression extends Node {
type: 'AssignmentExpression'
operator: AssignmentOperator
left: Expression
right: Expression
}
`

#### AssignmentOperator

`ts
type AssignmentOperator = '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '<<=' | '>>=' | '>>>=' | '|=' | '^=' | '&='
`

$3

A logical operation between two expressions.

`ts
interface LogicalExpression extends Node {
type: 'LogicalExpression'
operator: LogicalOperator
left: Expression
right: Expression
}
`

#### LogicalOperator

`ts
type LogicalOperator = '||' | '&&' | '^^'
`

$3

A member expression.

`ts
interface MemberExpression extends Node {
type: 'MemberExpression'
object: Expression
property: Expression
computed: boolean
}
`

$3

A conditional expression or ternary.

`ts
interface ConditionalExpression extends Node {
type: 'ConditionalExpression'
test: Expression
alternate: Expression
consequent: Expression
}
`

$3

A function call expression or struct initialization.

`ts
interface CallExpression extends Node {
type: 'CallExpression'
callee: Expression
arguments: Expression[]
}
``