@bigmistqke/view.gl 0.1.7 → 0.1.9

package/.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(grep:*)",
       "Bash(npm test:*)",
       "Bash(npm run build:*)",
-      "Bash(rg:*)"
+      "Bash(rg:*)",
+      "Bash(npm run lint:*)"
     ],
     "deny": []
   }

package/README.md

@@ -1,56 +1,62 @@
 # 👁️ @bigmistqke/view.gl
 
-🔧 Minimal library for managing WebGL uniforms / (interleaved) attributes / buffers / ...
+🔧 Utilities for managing WebGL resources: uniforms, (interleaved) attributes and buffers.
 
 - schema-based resource management [`view-gl`](#️-viewgl)
-- type-safe GLSL template literals to compose schemas [`view-gl/tag`](#️-viewgltag)
+- compose schema and shader simultaneously via a tag template literal [`view-gl/tag`](#️-viewgltag)
 
 ## Table of Contents
 
-- [📦 Install](#-install)
-- [👁️ view.gl](#️-viewgl)
-  - [🚀 Basic Usage](#-basic-usage)
-  - [👁️ view](#️-view)
-    - [📋 ViewSchema](#-viewschema)
-  - [👀 Resource Views](#-resource-views)
-    - [🎯 uniformView](#-uniformview)
-      - [📋 UniformSchema](#-uniformschema)
-    - [📝 attributeView](#-attributeview)
-      - [📋 AttributeSchema](#-attributeschema)
-    - [🔗 interleavedAttributeView](#-interleavedattributeview)
-      - [📋 InterleavedAttributeSchema](#-interleavedattributeschema)
-    - [🗂️ bufferView](#-bufferview)
-      - [📋 BufferSchema](#-bufferschema)
-- [🏷️ view.gl/tag](#️-viewgltag)
-  - [🚀 Basic Usage](#-basic-usage-1)
-  - [📝 glsl](#-glsl)
-    - [🧩 GLSL Fragment](#-glsl-fragment)
-    - [🔒 Symbol Variables](#-symbol-variables)
+- 📦 [Install](#-install)
+- 👁️ [view.gl](#️-viewgl)
+  - 🚀 [Basic Usage](#-basic-usage)
+  - 👁️ [view](#️-view)
+    - 📋 [ViewSchema](#-viewschema)
+  - 👀 [Resource Views](#-resource-views)
+    - 🎯 [uniformView](#-uniformview)
+      - 📋 [UniformSchema](#-uniformschema)
+    - 📝 [attributeView](#-attributeview)
+      - 📋 [AttributeSchema](#-attributeschema)
+    - 🔗 [interleavedAttributeView](#-interleavedattributeview)
+      - 📋 [InterleavedAttributeSchema](#-interleavedattributeschema)
+    - 🗂️ [bufferView](#-bufferview)
+      - 📋 [BufferSchema](#-bufferschema)
+- 🏷️ [view.gl/tag](#️-viewgltag)
+  - 🚀 [Basic Usage](#-basic-usage-1)
+  - 📝 [glsl](#-glsl)
+    - 🧩 [GLSL Fragment](#-glsl-fragment)
+    - 🔒 [Symbol Variables](#-symbol-variables)
     - [WebGL Version Support](#webgl-version-support)
-  - [⚙️ Resource Tags](#️-resource-tags)
-    - [🎯 uniform[kind](name, options?)](#-uniformkindname-options)
-    - [📝 attribute[kind](name, options?)](#-attributekindname-options)
-    - [🔗 interleave(name, layout, options?)](#-interleavename-layout-options)
-  - [⚙️ compile(gl, vertex, fragment)](#️-compilegl-vertex-fragment)
-    - [🔍 compile.toString(shader)](#-compiletostringshader)
-    - [📋 compile.toSchema(shader)](#-compiletoschemaschader)
-- [🛠️ Utils](#️-utils)
-  - [🏗️ createProgram](#️-createprogram)
-  - [🖼️ createTexture](#️-createtexture)
-  - [🖥️ createFramebuffer](#️-createframebuffer)
-- [🔍 WebGL Type Compatibility](#-webgl-type-compatibility)
-  - [🎯 Uniform Types](#-uniform-types)
-  - [📝 Attribute Types](#-attribute-types)
+  - 🏷️ [Resource Tokens](#️-resource-tokens)
+    - 🎯 [uniform[kind](name, options?)](#-uniformkindname-options)
+    - 📝 [attribute[kind](name, options?)](#-attributekindname-options)
+    - 🔗 [interleave(name, layout, options?)](#-interleavename-layout-options)
+  - ⚙️ [compile(gl, vertex, fragment)](#️-compilegl-vertex-fragment)
+    - 🔄 [compile.toQuad(gl, fragment)](#-compiletoquadgl-fragment-options)
+    - 🔍 [compile.toString(shader)](#-compiletostringshader)
+    - 📋 [compile.toSchema(shader)](#-compiletoschemaschader)
+- 🛠️ [Utils](#️-utils)
+  - 🏗️ [createProgram](#️-createprogram)
+  - 🖼️ [createTexture](#️-createtexture)
+  - 🖥️ [createFramebuffer](#️-createframebuffer)
+- 🔍 [WebGL Type Compatibility](#-webgl-type-compatibility)
+  - 🎯 [Uniform Types](#-uniform-types)
+  - 📝 [Attribute Types](#-attribute-types)
 
 ## 📦 Install
 
 ```shell
 npm install @bigmistqke/view.gl
-# or
+```
+```shell
 pnpm add @bigmistqke/view.gl
-# or
+```
+```shell
 yarn add @bigmistqke/view.gl
 ```
+```shell
+bun add @bigmistqke/view.gl
+```
 
 ## 👁️ view.gl
 
@@ -314,7 +320,7 @@ type BufferSchema = Record<string | symbol, BufferDefinition>
 
 ## 🏷️ view.gl/tag
 
-Type-safe GLSL template literals with automatic schema extraction.
+Type-safe GLSL template literals with automatic schema extraction and view creation.
 
 - **Embedded Resources**: Define uniforms, attributes, and interleaved layouts directly in GLSL
 - **Type Inference**: Automatically infers schema types and creates type-safe view
@@ -448,9 +454,9 @@ const shader = glsl`#version 300 es
 `
 ```
 
-### ⚙️ Resource Tags
+### 🏷️ Resource Tokens
 
-Functions for defining WebGL resources directly in GLSL templates. These tags generate GLSL declarations and automatically extract type-safe schemas for use with the view system.
+Utilities for defining WebGL resources directly in GLSL templates. These create metadata that the [`compile`](#️-compilegl-vertex-fragment-overrideschema) consumes to generate the typesafe schema and view.
 
 #### 🎯 uniform[kind](name, options?)
 
@@ -543,15 +549,48 @@ const vertexShader = glsl`
 
 ### ⚙️ compile(gl, vertex, fragment, overrideSchema?)
 
-Compiles shaders and extracts schema from embedded resources. Returns both the compiled program and a ready-to-use view.
+Compiles shaders to a `WebGLProgram` and extracts typesafe schema and view.
+
+### 🔄 compile.toQuad(gl, fragment, options?)
+
+Convenient helper for fullscreen quad rendering with fragment shaders. Automatically creates a vertex shader with a quad geometry and handles vertex buffer setup.
+
+```typescript
+const { program, schema, view } = compile.toQuad(gl, fragmentShader)
+
+// Ready to render - no vertex setup required
+view.uniforms.time.set(performance.now())
+gl.drawArrays(gl.TRIANGLES, 0, 6)
+```
+
+**Perfect for:**
+- Fragment shader effects (ray-marching, post-processing, etc.)
+- Fullscreen compute-style shaders
+- Quick prototyping and experimentation
+
+**Generated vertex shader:**
+- Creates `a_quad` attribute automatically
+- Outputs `uv` varying (same as vertex position: `[-1,1]` range)
+- Sets up clip-space quad covering the entire screen
+
+**Parameters:**
+- `gl`: WebGL rendering context
+- `fragment`: Fragment shader with embedded resources
+- `options`: Optional compilation options (same as `compile()`)
+
+**Returns:** Same as `compile()` with pre-configured quad rendering
 
 ```typescript
-const { program, schema, view } = compile(gl, vertexShader, fragmentShader)
+const { program, schema, view, vertex, fragment } = compile(gl, vertexShader, fragmentShader)
 
 // Use the view directly
 view.uniforms.time.set(performance.now())
 view.attributes.position.set(vertexData).bind()
 
+// Access the compiled shader strings
+console.log(vertex)                           // Compiled vertex shader GLSL
+console.log(fragment)                         // Compiled fragment shader GLSL
+
 // Or access the extracted schema
 console.log(schema.uniforms)                  // { time: { kind: 'float' }, ... }
 console.log(schema.attributes)                // { position: { kind: 'vec3' }, ... }
@@ -583,6 +622,8 @@ view.buffers.indices.set(indexData).bind()
 - `program`: Compiled WebGL program
 - `schema`: Merged schema (extracted + override)
 - `view`: Ready-to-use view with type-safe resource access
+- `vertex`: Compiled vertex shader GLSL string
+- `fragment`: Compiled fragment shader GLSL string
 
 #### 🔍 compile.toString(shader)
 

package/dev/src/examples/bezier.ts

@@ -1,8 +1,8 @@
 import { attribute, compile, glsl, interleave, uniform } from 'view.gl/tag'
-import { createElement, cursor } from '../utils'
+import { cursor, dom } from '../utils'
 
 // Create canvas and WebGL context
-const canvas = createElement('canvas')
+const canvas = dom('canvas', { parentElement: document.body })
 canvas.width = window.innerWidth
 canvas.height = window.innerHeight
 const gl = canvas.getContext('webgl2', { antialias: true })!
@@ -357,6 +357,7 @@ updateLineData()
 /**********************************************************************************/
 
 function render() {
+  console.log('render!')
   // Update canvas size if window was resized
   if (canvas.width !== window.innerWidth || canvas.height !== window.innerHeight) {
     canvas.width = window.innerWidth

package/dev/src/examples/game-of-life.ts

@@ -1,10 +1,11 @@
 import { FramebufferDefinition } from 'src/types'
 import { createFramebuffer } from 'src/utils'
-import { attribute, compile, glsl, uniform } from 'view.gl/tag'
+import { compile, glsl, uniform } from 'view.gl/tag'
+import { dom } from '../utils'
 
 let playing = false
 
-const canvas = document.createElement('canvas')
+const canvas = dom('canvas')
 const gl = canvas.getContext('webgl', { antialias: false })!
 if (!gl) {
   throw new Error('WebGL not supported')
@@ -85,18 +86,6 @@ canvas.height = 256 * 2
 const WIDTH = canvas.width
 const HEIGHT = canvas.height
 
-// --- Shaders ---
-
-// Vertex shader (simple fullscreen quad)
-const vertex = glsl`
-  ${attribute.vec2('a_vertex')}
-  varying vec2 v_uv;
-  void main() {
-    v_uv = a_vertex * 0.5 + 0.5;
-    gl_Position = vec4(a_vertex, 0, 1);
-  }
-`
-
 // Fragment shader for Game of Life step
 // We read from u_texture the current state
 // Alive cells are red > 0.5, dead < 0.5
@@ -115,15 +104,17 @@ const stepFragment = glsl`
   }
 
   void main() {
+    vec2 uv  = v_uv * 0.5 + 0.5;
+
     int sum = 0;
     // Iterate neighbors -1,0,1
     for (int y = -1; y <= 1; y++) {
       for (int x = -1; x <= 1; x++) {
         if (x == 0 && y == 0) continue;
-        sum += getCell(v_uv + vec2(float(x), float(y)) * u_texelSize);
+        sum += getCell(uv + vec2(float(x), float(y)) * u_texelSize);
       }
     }
-    int current = getCell(v_uv);
+    int current = getCell(uv);
 
     int nextState = 0;
     if (current == 1) {
@@ -144,22 +135,14 @@ const renderFragment = glsl`
   ${uniform.sampler2D('u_texture')}
   
   void main() {
-    float cell = texture2D(u_texture, v_uv).r;
+    vec2 uv  = v_uv * 0.5 + 0.5;
+    float cell = texture2D(u_texture, uv).r;
     gl_FragColor = vec4(vec3(cell), 1.0);
   }`
 
 // --- Create programs ---
-const { program: stepProgram, view: stepView } = compile(gl, vertex, stepFragment)
-const { program: renderProgram, view: renderView } = compile(gl, vertex, renderFragment, {
-  attributes: {
-    a_vertex: {
-      buffer: stepView.attributes.a_vertex.buffer,
-    },
-  },
-})
-
-// Setup quad
-stepView.attributes.a_vertex.set(new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]))
+const { program: stepProgram, view: stepView } = compile.toQuad(gl, stepFragment)
+const { program: renderProgram, view: renderView } = compile.toQuad(gl, renderFragment)
 
 // Initialize two framebuffers (with their respective texture) for ping-pong
 const framebufferOptions = {
@@ -210,7 +193,7 @@ function step() {
   stepView.uniforms.u_texture.set(0)
   stepView.uniforms.u_texelSize.set(1 / WIDTH, 1 / HEIGHT)
 
-  stepView.attributes.a_vertex.bind()
+  stepView.attributes.a_quad.bind()
 
   gl.drawArrays(gl.TRIANGLES, 0, 6)
 }
@@ -225,7 +208,7 @@ function render() {
   gl.bindTexture(gl.TEXTURE_2D, write.texture)
   renderView.uniforms.u_texture.set(0)
 
-  renderView.attributes.a_vertex.bind()
+  renderView.attributes.a_quad.bind()
 
   gl.drawArrays(gl.TRIANGLES, 0, 6)
 }

package/dev/src/examples/glsl-composition.ts

@@ -8,13 +8,13 @@
  */
 
 import { attribute, compile, glsl, uniform } from 'view.gl/tag'
-import { createElement } from '../utils'
+import { dom } from '../utils'
 
-const canvas = createElement('canvas', {
+const canvas = dom('canvas', {
   width: window.innerWidth,
   height: window.innerHeight,
   parentElement: document.body,
-  style: 'width: 100%; height: 100%',
+  style: { width: '100%' },
 })
 
 const gl = canvas.getContext('webgl2')!

package/dev/src/examples/grid.ts

@@ -1,7 +1,11 @@
 import { attribute, compile, glsl, uniform } from 'view.gl/tag'
-import { createElement, cursor } from '../utils'
+import { cursor, dom } from '../utils'
 
-const canvas = createElement('canvas', { width: window.innerWidth, height: window.innerHeight })
+const canvas = dom('canvas', {
+  width: window.innerWidth,
+  height: window.innerHeight,
+  parentElement: document.body,
+})
 const gl = canvas.getContext('webgl2', { antialias: false })!
 
 if (!gl) {
@@ -14,7 +18,7 @@ const state = {
   elements: [] as Array<ReturnType<typeof createGridElement>>,
 }
 
-const container = createElement('div')
+const container = dom('div', { parentElement: document.body })
 state.elements.push(createGridElement({ x: 100, y: 100 }))
 
 /**********************************************************************************/
@@ -29,28 +33,30 @@ function createGridElement(position = { x: 0, y: 0 }) {
     y: (position.y - state.position.y) / state.scale,
   }
 
-  const element = createElement('div', {
+  const div = dom('div', {
     innerText: 'HALLO WORLD',
-    style: `position: fixed; 
-z-index: 10; 
-left: 0px; 
-top: 0px; 
-transform-origin: top left; 
-background: white; 
-padding: 2px; 
-border-radius: 2px;`,
+    style: {
+      position: 'fixed',
+      zIndex: '10',
+      left: '0px',
+      top: '0px',
+      transformOrigin: 'top left',
+      background: 'white',
+      padding: '2px',
+      borderRadius: '2px',
+    },
     parentElement: container,
   })
 
   function update() {
-    element.style.transform = `translate3d(${state.position.x + position.x * state.scale}px,${
+    div.style.transform = `translate3d(${state.position.x + position.x * state.scale}px,${
       state.position.y + position.y * state.scale
     }px,0) scale(${state.scale})`
   }
   update()
 
   return {
-    element,
+    element: div,
     position,
     update,
   }

package/dev/src/examples/pix-sim.ts

@@ -1,7 +1,7 @@
 import { FramebufferDefinition } from 'src/types'
 import { createFramebuffer } from 'src/utils'
 import { attribute, compile, glsl, uniform } from 'view.gl/tag'
-import { createElement } from '../utils'
+import { dom } from '../utils'
 
 export const MATERIALS = {
   SAND: {
@@ -24,36 +24,41 @@ let playing = false
 let currentMaterial: (typeof MATERIALS)[keyof typeof MATERIALS]['id'] = MATERIALS.SAND.id
 
 // Create UI container
-const container = createElement('div', {
-  style: 'display: flex; flex-direction: column; align-items: center; gap: 10px;',
+const container = dom('div', {
+  style: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    gap: '10px',
+  },
   parentElement: document.body,
 })
 
 // Create material buttons
-const buttonContainer = createElement('div', {
+const buttonContainer = dom('div', {
   style: 'display: flex; gap: 10px; margin-bottom: 10px;',
   parentElement: container,
 })
 
 Object.entries(MATERIALS).forEach(([name, material]) => {
-  createElement('button', {
-    textContent: name.toLowerCase(),
+  dom('button', {
     'data-name': name,
     'data-id': material.id.toString(),
-    style: `padding: 5px 10px;
-    font-size: 14px;
-    font-family: arial;
-    cursor: pointer;
-    color: black;
-    background: ${
-      currentMaterial === material.id
-        ? `rgb(${material.color.map(c => Math.floor(c * 255)).join(',')})`
-        : `rgba(${material.color.map(c => Math.floor(c * 255)).join(',')}, 0.75)`
-    };
-    border-color: ${name === 'SAND' ? 'black' : 'white'};
-    border: 2px solid rgb(${material.color.map(c => Math.floor(c * 255)).join(',')});
-    border-radius: 2px;
-  `,
+    textContent: name.toLowerCase(),
+    style: {
+      padding: '5px 10px',
+      fontSize: '14px',
+      fontFamily: 'arial',
+      cursor: 'pointer',
+      color: 'black',
+      background:
+        currentMaterial === material.id
+          ? `rgb(${material.color.map(c => Math.floor(c * 255)).join(',')})`
+          : `rgba(${material.color.map(c => Math.floor(c * 255)).join(',')}, 0.75)`,
+      borderColor: name === 'SAND' ? 'black' : 'white',
+      border: `2px solid rgb(${material.color.map(c => Math.floor(c * 255)).join(',')})`,
+      borderRadius: '2px',
+    },
     onclick() {
       currentMaterial = material.id
       // Update all button borders
@@ -79,7 +84,7 @@ function spray() {
   return Math.floor(Math.random() * 8) * (Math.random() < 0.5 ? 1 : -1)
 }
 
-const canvas = createElement('canvas', {
+const canvas = dom('canvas', {
   parentElement: container,
   onmousedown() {
     const rect = canvas.getBoundingClientRect()
@@ -462,7 +467,9 @@ void main() {
 // --- Create programs ---
 const { program: stepProgram, view: stepView } = compile(gl, vertex, stepFragment)
 const { program: renderProgram, view: renderView } = compile(gl, vertex, renderFragment, {
-  attributes: { a_vertex: { buffer: stepView.attributes.a_vertex.buffer } },
+  schema: {
+    attributes: { a_vertex: { buffer: stepView.attributes.a_vertex.buffer } },
+  },
 })
 
 gl.useProgram(renderProgram)