@bigmistqke/view.gl 0.1.1 → 0.1.3

package/README.md

@@ -1,41 +1,66 @@
-# view.gl
+# 👁️ @bigmistqke/view.gl
 
-Minimal library for WebGL shader resource management with type-safe GLSL template literals.
+🔧 Minimal library for managing WebGL uniforms / (interleaved) attributes / buffers / ...
+
+- schema-based resource management [`view-gl`](#️-viewgl)
+- type-safe GLSL template literals to compose schemas [`view-gl/tag`](#️-viewgltag)
 
 ## Table of Contents
 
-- [View](#view)
-  - [Basic Usage](#basic-usage)
-  - [View Types](#view-types)
-    - [uniformView](#uniformview)
-    - [attributeView](#attributeview)
-    - [interleavedAttributeView](#interleavedattributeview)
-    - [bufferView](#bufferview)
-  - [Drawing Examples](#drawing-examples)
-    - [Regular Drawing](#regular-drawing)
-    - [Instanced Drawing](#instanced-drawing)
-  - [Features](#features)
-- [Tag](#tag)
-  - [Basic Usage](#basic-usage-1)
-  - [Template Features](#template-features)
-  - [Tag Functions](#tag-functions)
-  - [Supported Types](#supported-types)
-- [Utils](#utils)
-  - [WebGL Utilities](#webgl-utilities)
-  - [Type Utilities](#type-utilities)
-  - [Type Guards](#type-guards)
-  - [Resource Creation](#resource-creation)
-
-## View
+- [📦 Install](#-install)
+- [👁️ view.gl](#️-viewgl)
+  - [🚀 Basic Usage](#-basic-usage)
+  - [👀 View Types](#-view-types)
+    - [🎯 uniformView](#-uniformview)
+    - [📝 attributeView](#-attributeview)
+    - [🔗 interleavedAttributeView](#-interleavedattributeview)
+    - [🗂️ bufferView](#-bufferview)
+  - [🎨 Drawing Examples](#-drawing-examples)
+    - [🖼️ Regular Drawing](#-regular-drawing)
+    - [📱 Instanced Drawing](#-instanced-drawing)
+- [🏷️ view.gl/tag](#️-viewgltag)
+  - [🚀 Basic Usage](#-basic-usage-1)
+  - [📝 Template Features](#-template-features)
+  - [⚙️ Tag Functions](#️-tag-functions)
+    - [🎯 uniform[kind](name, options?)](#-uniformkindname-options)
+    - [📝 attribute[kind](name, options?)](#-attributekindname-options)
+    - [🔗 interleave(name, layout, options?)](#-interleavename-layout-options)
+    - [📝 glsl](#-glsl)
+    - [⚙️ compile(gl, vertex, fragment)](#️-compilegl-vertex-fragment)
+  - [🔣 Symbol Support](#-symbol-support)
+- [🛠️ Utils](#️-utils)
+  - [🏗️ createProgram](#️-createprogram)
+  - [🖼️ createTexture](#️-createtexture)
+  - [🖥️ createFramebuffer](#️-createframebuffer)
+
+## 📦 Install
+
+```shell
+npm install @bigmistqke/view.gl
+```
+
+```shell
+pnpm add @bigmistqke/view.gl
+```
+
+```shell
+yarn add @bigmistqke/view.gl
+```
+
+```shell
+bun add @bigmistqke/view.gl
+```
+
+## 👁️ view.gl
 
 The view system provides type-safe WebGL resource management for uniforms, attributes, and buffers.
 
-### Basic Usage
+### 🚀 Basic Usage
 
 ```typescript
-import { view } from 'view.gl'
+import { view } from '@bigmistqke/view.gl'
 
-const resources = view(gl, program, {
+const { uniforms, attributes } = view(gl, program, {
   uniforms: {
     time: { kind: 'float' },
     resolution: { kind: 'vec2' },
@@ -50,28 +75,33 @@ const resources = view(gl, program, {
 })
 
 // Type-safe uniform setting
-resources.uniforms.time.set(performance.now())
-resources.uniforms.resolution.set(canvas.width, canvas.height)
+uniforms.time.set(performance.now())
+uniforms.resolution.set(canvas.width, canvas.height)
 
 // Attribute management
-resources.attributes.position.set(positionData)
-resources.attributes.position.bind()
+attributes.position.set(positionData)
+attributes.position.bind()
 ```
 
-### View Types
+### 👀 View Types
 
 Each view type can be imported individually too.
 
 ```typescript
-import { uniformView, attributeView, interleavedAttributeView, bufferView } from 'view.gl'
+import {
+  uniformView,
+  attributeView,
+  interleavedAttributeView,
+  bufferView,
+} from '@bigmistqke/view.gl'
 ```
 
-#### uniformView
+#### 🎯 uniformView
 
 Manages shader uniform variables.
 
 ```typescript
-import { uniformView } from 'view.gl'
+import { uniformView } from '@bigmistqke/view.gl'
 
 const uniforms = uniformView(gl, program, {
   time: { kind: 'float' },
@@ -89,12 +119,12 @@ uniforms.transform.set(transformMatrix)
 - `kind`: GLSL type (`'float'`, `'vec2'`, `'mat4'`, `'sampler2D'`, etc.)
 - `size`: Array size (optional) - converts uniform to array type with Float32Array setter
 
-#### attributeView
+#### 📝 attributeView
 
 Manages vertex attributes with buffer creation, binding, and data management.
 
 ```typescript
-import { attributeView } from 'view.gl'
+import { attributeView } from '@bigmistqke/view.gl'
 
 const attributes = attributeView(gl, program, {
   position: { kind: 'vec3' },
@@ -120,25 +150,25 @@ gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, 100)
 - `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
 - `buffer`: Custom WebGLBuffer (optional) - uses auto-created buffer if not provided
 
-#### interleavedAttributeView
+#### 🔗 interleavedAttributeView
 
 Manages interleaved vertex data with automatic stride/offset calculation and VAO optimization.
 
 ```typescript
-import { interleavedAttributeView } from 'view.gl'
+import { interleavedAttributeView } from '@bigmistqke/view.gl'
 
 const interleavedAttributes = interleavedAttributeView(gl, program, {
   vertexData: {
     layout: [
-      { name: 'position', kind: 'vec3' },
-      { name: 'normal', kind: 'vec3' },
-      { name: 'uv', kind: 'vec2' },
+      { key: 'position', kind: 'vec3' },
+      { key: 'normal', kind: 'vec3' },
+      { key: 'uv', kind: 'vec2' },
     ],
   },
   instanceData: {
     layout: [
-      { name: 'instancePos', kind: 'vec2' },
-      { name: 'instanceColor', kind: 'vec3' },
+      { key: 'instancePos', kind: 'vec2' },
+      { key: 'instanceColor', kind: 'vec3' },
     ],
     instanced: true,
   },
@@ -158,12 +188,12 @@ interleavedAttributes.instanceData.bind()
 - `layout`: Array of attribute definitions with `name` and `kind`
 - `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes in layout
 
-#### bufferView
+#### 🗂️ bufferView
 
 Manages generic WebGL buffers for various uses.
 
 ```typescript
-import { bufferView } from 'view.gl'
+import { bufferView } from '@bigmistqke/view.gl'
 
 const buffers = bufferView(gl, {
   indices: { target: 'ELEMENT_ARRAY_BUFFER' },
@@ -182,9 +212,9 @@ buffers.data.bind()
 - `target`: Buffer target (`'ARRAY_BUFFER'`, `'ELEMENT_ARRAY_BUFFER'`)
 - `usage`: Usage pattern (`'STATIC_DRAW'`, `'DYNAMIC_DRAW'`, `'STREAM_DRAW'`)
 
-### Drawing Examples
+### 🎨 Drawing Examples
 
-#### Regular Drawing
+#### 🖼️ Regular Drawing
 
 ```typescript
 const { attributes } = view(gl, program, {
@@ -200,7 +230,7 @@ attributes.uv.set(uvData).bind()
 gl.drawArrays(gl.TRIANGLES, 0, vertexCount)
 ```
 
-#### Instanced Drawing
+#### 📱 Instanced Drawing
 
 ```typescript
 const { attributes } = view(gl, program, {
@@ -218,86 +248,258 @@ attributes.instanceColor.set(instanceColors).bind()
 gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, instanceCount)
 ```
 
-### Features
+## 🏷️ view.gl/tag
+
+The tag system provides GLSL template literal support with embedded schema definitions.
+
+### 🚀 Basic Usage
 
-- **Automatic Resource Management**: Buffer creation, disposal, and cleanup
-- **Type Safety**: Compile-time type checking for uniform and attribute operations
-- **WebGL Extensions**: Automatic fallback for instanced arrays and vertex array objects
-- **Memory Management**: AbortSignal support for resource cleanup
+```typescript
+import { glsl, uniform, attribute, compile } from '@bigmistqke/view.gl/tag'
 
-## Tag
+const vertexShader = glsl`
+  ${attribute.vec3('position')}
+  ${attribute.vec2('uv')}
+  ${uniform.mat4('projection')}
+  ${uniform.mat4('model')}
+  
+  varying vec2 vUv;
+  
+  void main() {
+    vUv = uv;
+    gl_Position = projection * model * vec4(position, 1.0);
+  }
+`
+
+const fragmentShader = glsl`
+  ${uniform.sampler2D('texture')}
+  
+  varying vec2 vUv;
+  
+  void main() {
+    gl_FragColor = texture2D(texture, vUv);
+  }
+`
 
-The tag system provides GLSL template literal support with embedded resource definitions.
+const { program, schema } = compile(gl, vertexShader, fragmentShader)
+```
 
-### Template Features
+### 📝 Template Features
 
 - **Embedded Resources**: Define uniforms and attributes directly in GLSL
 - **Type Safety**: Automatic schema generation from template literals
 - **WebGL Version Support**: Automatic syntax conversion for WebGL1/2
 - **Interleaved Attributes**: Multi-attribute layout support
+- **Symbol Support**: Use JavaScript symbols as keys (see [Symbol Support](#-symbol-support))
 
-### Tag Functions
+### ⚙️ Tag Functions
 
-- `uniform[kind](name, options?)`: Define uniform variables
-- `attribute[kind](name, options?)`: Define vertex attributes
-- `interleave(name, layout, options?)`: Define interleaved attribute layouts
-- `glsl`: Template literal processor for GLSL code
-- `compile(gl, vertex, fragment)`: Compile shaders and extract schema
+#### 🎯 uniform[kind](name, options?)
 
-### Basic Usage
+Define uniform variables in GLSL templates. Supports all GLSL uniform types.
 
 ```typescript
-import { glsl, uniform, attribute, compile } from 'view.gl/tag'
+import { uniform, glsl } from '@bigmistqke/view.gl/tag'
+
+const shader = glsl`
+  ${uniform.float('time')}
+  ${uniform.vec2('resolution')}
+  ${uniform.mat4('projection')}
+  ${uniform.sampler2D('texture')}
+  ${uniform.vec3('lights', { size: 8 })} // Array uniform: vec3[8]
+  
+  void main() {
+    // Use uniforms in shader code
+  }
+`
+```
+
+**Available types**: `float`, `int`, `bool`, `vec2`, `vec3`, `vec4`, `ivec2`, `ivec3`, `ivec4`, `bvec2`, `bvec3`, `bvec4`, `mat2`, `mat3`, `mat4`, `sampler2D`, `samplerCube`
+
+**Options**:
+
+- `size`: Array size (creates array uniform with Float32Array setter)
+
+#### 📝 attribute[kind](name, options?)
+
+Define vertex attributes in GLSL templates.
+
+```typescript
+import { attribute, glsl } from '@bigmistqke/view.gl/tag'
 
 const vertexShader = glsl`
   ${attribute.vec3('position')}
   ${attribute.vec2('uv')}
-  ${uniform.mat4('projection')}
-  ${uniform.mat4('model')}
+  ${attribute.vec3('normal')}
+  ${attribute.vec2('instanceOffset', { instanced: true })}
   
-  varying vec2 vUv;
+  void main() {
+    gl_Position = vec4(position + vec3(instanceOffset, 0.0), 1.0);
+  }
+`
+```
+
+**Available types**: `float`, `vec2`, `vec3`, `vec4`, `mat2`, `mat3`, `mat4`, `int`, `ivec2`, `ivec3`, `ivec4`
+
+**Options**:
+
+- `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
+- `buffer`: Custom WebGLBuffer (optional)
+
+#### 🔗 interleave(name, layout, options?)
+
+Define interleaved attribute layouts for efficient vertex data.
+
+```typescript
+import { interleave, glsl } from '@bigmistqke/view.gl/tag'
+
+const vertexShader = glsl`
+  ${interleave('vertexData', [
+    { key: 'position', kind: 'vec3' },
+    { key: 'normal', kind: 'vec3' },
+    { key: 'uv', kind: 'vec2' },
+  ])}
+  
+  ${interleave(
+    'instanceData',
+    [
+      { key: 'instancePos', kind: 'vec2' },
+      { key: 'instanceColor', kind: 'vec3' },
+    ],
+    { instanced: true },
+  )}
   
   void main() {
-    vUv = uv;
-    gl_Position = projection * model * vec4(position, 1.0);
+    gl_Position = vec4(position + vec3(instancePos, 0.0), 1.0);
   }
 `
+```
 
-const fragmentShader = glsl`
-  ${uniform.sampler2D('texture')}
+**Layout format**:
+
+- `key`: Attribute name
+- `kind`: GLSL type
+
+**Options**:
+
+- `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes
+
+#### 📝 glsl
+
+Template literal processor that handles GLSL code and embedded resources.
+
+```typescript
+import { glsl } from '@bigmistqke/view.gl/tag'
+
+const shader = glsl`
+  precision mediump float;
   
-  varying vec2 vUv;
+  ${uniform.vec2('resolution')}
   
   void main() {
-    gl_FragColor = texture2D(texture, vUv);
+    vec2 uv = gl_FragCoord.xy / resolution;
+    gl_FragColor = vec4(uv, 0.0, 1.0);
   }
 `
+```
+
+#### ⚙️ compile(gl, vertex, fragment)
+
+Compiles shaders and extracts schema from embedded resources.
+
+```typescript
+import { compile } from '@bigmistqke/view.gl/tag'
 
 const { program, schema } = compile(gl, vertexShader, fragmentShader)
+
+// Schema contains extracted uniforms, attributes, and buffers
+console.log(schema.uniforms) // { time: { kind: 'float' }, ... }
+console.log(schema.attributes) // { position: { kind: 'vec3' }, ... }
 ```
 
-## Utils
+**Returns**:
+
+- `program`: Compiled WebGL program
+- `schema`: Extracted resource definitions for use with `view()`
+
+### 🔣 Symbol Support
+
+Symbols are supported as keys for uniforms, attributes, and buffers. When interpolated in glsl templates, they're automatically converted to valid GLSL identifiers. This prevents naming collisions between different shader modules and enables private scoping of shader variables.
+
+```typescript
+const u_time = Symbol('time')
+const a_position = Symbol('position')
+
+const shader = glsl`
+  ${attribute.vec3(a_position)}
+  ${uniform.float(u_time)}
+  
+  void main() {
+    gl_Position = vec4(${a_position}, ${u_time});
+  }
+`
+```
+
+<details>
+<summary>Usage with vanilla view.gl</summary>
+
+When manually constructing GLSL strings, use `toID()` to convert symbols to valid identifiers:
+
+```typescript
+import { createProgram, view, toID } from 'view.gl'
+
+const u_time = Symbol('time')
+const a_position = Symbol('position')
+
+const vertex = `
+  attribute vec3 ${toID(a_position)};
+  uniform float ${toID(u_time)};
+
+  void main() {
+    gl_Position = vec4(${toID(a_position)}, ${toID(u_time)});
+  }
+`
+
+const fragment = `
+  precision mediump float;
+  uniform float ${toID(u_time)};
+
+  void main() {
+    gl_FragColor = vec4(1.0, 1.0, 1.0, sin(${toID(u_time)}));
+  }
+`
+
+const program = createProgram(gl, vertex, fragment)
+
+const { attributes, uniforms } = view(gl, program, {
+  uniforms: { [u_time]: { kind: 'float' } },
+  attributes: { [a_position]: { kind: 'vec3' } },
+})
+
+attributes[a_position].set(vertexData)
+uniforms[u_time].set(performance.now())
+```
 
-WebGL utilities and helper functions.
+</details>
 
-### WebGL Utilities
+## 🛠️ Utils
 
-#### createProgram
+### 🏗️ createProgram
 
 Creates and links a WebGL program from vertex and fragment shader sources.
 
 ```typescript
-import { createProgram } from 'view.gl/utils'
+import { createProgram } from '@bigmistqke/view.gl/utils'
 
 const program = createProgram(gl, vertexShaderSource, fragmentShaderSource)
 ```
 
-#### createTexture
+### 🖼️ createTexture
 
 Creates a WebGL texture with specified parameters.
 
 ```typescript
-import { createTexture } from 'view.gl/utils'
+import { createTexture } from '@bigmistqke/view.gl/utils'
 
 const texture = createTexture(
   gl,
@@ -318,12 +520,12 @@ const texture = createTexture(
 
 Automatically validates WebGL2-only formats and provides fallbacks for WebGL1.
 
-#### createFramebuffer
+### 🖥️ createFramebuffer
 
 Creates a framebuffer with attached texture for render-to-texture operations.
 
 ```typescript
-import { createFramebuffer } from 'view.gl/utils'
+import { createFramebuffer } from '@bigmistqke/view.gl/utils'
 
 const { framebuffer, texture } = createFramebuffer(gl, {
   width: 512,

package/dev/404.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>view.gl</title>
+  <script>
+    // Redirect to index.html with the current path as a query parameter
+    const path = window.location.pathname.slice(1); // Remove leading slash
+    if (path) {
+      window.location.replace(window.location.origin + '/?redirect=' + path);
+    } else {
+      window.location.replace(window.location.origin);
+    }
+  </script>
+</head>
+<body>
+  Redirecting...
+</body>
+</html>

package/dev/dist/404.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>view.gl</title>
+  <script>
+    // Redirect to index.html with the current path as a query parameter
+    const path = window.location.pathname.slice(1); // Remove leading slash
+    if (path) {
+      window.location.replace(window.location.origin + '/?redirect=' + path);
+    } else {
+      window.location.replace(window.location.origin);
+    }
+  </script>
+</head>
+<body>
+  Redirecting...
+</body>
+</html>