https://github.com/lewisgoing/webgltools
a library of tools for debugging web-3d webGL/threejs stuff
https://github.com/lewisgoing/webgltools
3d creative-coding glsl threejs web3d webgl webgl2
Last synced: 17 days ago
JSON representation
a library of tools for debugging web-3d webGL/threejs stuff
- Host: GitHub
- URL: https://github.com/lewisgoing/webgltools
- Owner: lewisgoing
- License: mit
- Created: 2025-08-26T01:15:48.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-26T06:42:40.000Z (9 months ago)
- Last Synced: 2025-08-26T08:34:35.762Z (9 months ago)
- Topics: 3d, creative-coding, glsl, threejs, web3d, webgl, webgl2
- Language: TypeScript
- Homepage: https://webgltools.lewisgo.ing
- Size: 399 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# WebGL Debugging Toolkit
[](https://www.npmjs.com/package/@webgltools/core)
[](https://www.npmjs.com/package/@webgltools/core)
[](https://github.com/lewisgoing?tab=packages&repo_name=webgl-tools)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://www.khronos.org/webgl/)
[](https://www.google.com/chrome/)
[](https://www.mozilla.org/firefox/)
[](https://www.apple.com/safari/)
[](https://www.microsoft.com/edge)
Live Demo •
Installation •
Quick Start •
Docs •
Features
A comprehensive, production-ready WebGL debugging and profiling toolkit that works with WebGL1 & WebGL2, raw GL and Three.js, with minimal overhead and safe fallbacks.
---
### See It In Action
```javascript
// 1. Import and initialize
import { WebGLDebugger } from '@webgltools/core';
const debug = new WebGLDebugger(gl, { mode: 'sampled' });
// 2. Wrap your render loop
function render() {
debug.beginFrame();
// Your WebGL code here
gl.drawArrays(gl.TRIANGLES, 0, count);
debug.endFrame();
console.log(`FPS: ${debug.fps} | Draw Calls: ${debug.drawCalls}`);
}
// 3. Add visual overlay (optional)
import('@webgltools/overlay').then(({ mountOverlay }) => {
mountOverlay(debug);
});
```
---
### Why WebGL Tools?
**Ultra-Low Overhead**
Smart sampling keeps your FPS high
**Deep Insights**
GPU timers, memory tracking, draw analysis
**Framework Agnostic**
Works with raw WebGL, Three.js, and more
**Production Ready**
Safe fallbacks, no crashes, TypeScript
---
## Features
### Core Debugging
- **Performance Metrics**: Real-time FPS, CPU/GPU timing, draw calls, triangles, texture binds, shader switches
- **Resource Tracking**: Monitor WebGL resource creation/deletion with estimated memory usage
- **GPU Timers**: Hardware-accelerated timing with WebGL1 & WebGL2 support
- **Low Overhead**: Sampled mode for production monitoring with minimal performance impact
### Enhanced Features
- **Shader Error Formatter**: Enhanced error messages with line-by-line source code highlighting
- **FBO Inspector**: Visualize render targets, capture framebuffers, analyze pixels with histogram support
- **Enhanced GPU Timers**: Hierarchical timing, per-draw-call metrics, bottleneck analysis
- **Performance Profiler**: Comprehensive device profiling, benchmark suite, HTML report generation
### Framework Support
- **Three.js Integration**: Drop-in adapter with automatic triangle counting
- **React Overlay**: Customizable debug panels with real-time updates
- **Spector.js Bridge**: Enhanced metadata for Spector.js integration
## Installation
Install from npm (recommended):
```bash
# Using pnpm (recommended)
pnpm add @webgltools/core
# Using npm
npm install @webgltools/core
# Using yarn
yarn add @webgltools/core
```
Or install from GitHub Packages:
```bash
# Configure npm to use GitHub Packages
echo "@webgltools:registry=https://npm.pkg.github.com" >> ~/.npmrc
# Install
npm install @webgltools/core
```
## Quick Start
```typescript
import { WebGLDebugger } from '@webgltools/core';
// 1. Get WebGL context
const canvas = document.querySelector('canvas')!;
const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
// 2. Create debugger instance
const debug = new WebGLDebugger(gl, {
mode: 'sampled', // 'off' | 'sampled' | 'full'
sampleRate: 0.3, // 30% sampling rate
logCreates: false // Log resource creation
});
// 3. Wrap your render loop
function render() {
debug.beginFrame();
// Your WebGL rendering code here
gl.drawArrays(gl.TRIANGLES, 0, vertexCount);
debug.endFrame();
// Get metrics
const snapshot = debug.getSnapshot();
console.log(`FPS: ${snapshot.fps}, Draw Calls: ${snapshot.drawCalls}`);
requestAnimationFrame(render);
}
// 4. Optional: Add visual overlay
import('@webgltools/overlay').then(({ mountOverlay }) => {
mountOverlay(debug);
});
```
## Three.js Integration
```typescript
import { WebGLDebugger } from '@webgltools/core';
import { attachThreeAdapter } from '@webgltools/three-adapter';
import * as THREE from 'three';
const renderer = new THREE.WebGLRenderer();
const gl = renderer.getContext();
const debug = new WebGLDebugger(gl, { mode: 'full' });
// Attach adapter for accurate triangle counting
attachThreeAdapter(renderer, debug);
// Use as normal
function animate() {
debug.beginFrame();
renderer.render(scene, camera);
debug.endFrame();
requestAnimationFrame(animate);
}
```
## Enhanced Features Usage
### Shader Error Formatting
```typescript
import { ShaderErrorFormatter } from '@webgltools/core';
// Compile shader with enhanced error reporting
const shader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(shader, shaderSource);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
const log = gl.getShaderInfoLog(shader);
const formatted = ShaderErrorFormatter.formatShaderError(shaderSource, log, 'vertex');
console.error(formatted.formattedOutput);
}
```
### FBO Inspector
```typescript
import { FBOInspector } from '@webgltools/core';
const inspector = new FBOInspector(gl);
// Capture current framebuffer
const imageData = inspector.captureFramebuffer();
// Save as image
const blob = await inspector.captureAsBlob(null, 'image/png');
// Analyze pixel at position
const pixel = inspector.inspectPixel(x, y);
console.log(`Color: ${pixel.hex}, RGB: ${pixel.rgba}`);
// Generate histogram
const histogram = inspector.createHistogram(null, 'luminance');
```
### Performance Profiling
```typescript
import { PerformanceProfiler } from '@webgltools/core';
const profiler = new PerformanceProfiler(gl);
// Run comprehensive benchmark
const profile = await profiler.generateProfile();
// Generate HTML report
const htmlReport = profiler.generateHTMLReport(profile);
// Export as JSON
const json = profiler.exportProfile(profile);
```
## Operating Modes
Choose the right mode for your use case:
| Mode | Performance Impact | Use Case | Features |
|------|-------------------|----------|----------|
| `off` | None | Production | No instrumentation |
| `sampled` | ~1-2% | Production monitoring | Statistical sampling |
| `full` | ~5-10% | Development | Complete tracking |
```javascript
// Production with monitoring
const debug = new WebGLDebugger(gl, {
mode: 'sampled',
sampleRate: 0.1 // 10% sampling
});
// Development debugging
const debug = new WebGLDebugger(gl, {
mode: 'full',
logCreates: true
});
```
## Package Structure
| Package | Description | Version |
|---------|-------------|---------|
| [`@webgltools/core`](https://www.npmjs.com/package/@webgltools/core) | Core debugging functionality |  |
| [`@webgltools/overlay`](https://www.npmjs.com/package/@webgltools/overlay) | React-based visual overlay |  |
| [`@webgltools/three-adapter`](https://www.npmjs.com/package/@webgltools/three-adapter) | Three.js integration |  |
| [`@webgltools/spector-bridge`](https://www.npmjs.com/package/@webgltools/spector-bridge) | Spector.js metadata support |  |
## Development
```bash
# Clone repository
git clone https://github.com/your-username/webgl-tools.git
cd webgl-tools
# Install dependencies
pnpm install
# Build all packages
pnpm build:packages
# Run tests
pnpm test
# Run playground
pnpm dev:playground
```
## Testing
The toolkit includes comprehensive test coverage:
```bash
# Run all tests
pnpm test
# Run unit tests only
pnpm test:unit
# Run E2E tests
pnpm test:e2e
# Generate coverage report
pnpm test:coverage
```
## Documentation
- [Architecture Overview](docs/PLAN.md)
- [Testing Strategy](docs/TEST_PLAN.md)
- [Enhanced Features](docs/ENHANCEMENT_PLAN.md)
- [API Reference](docs/API.md) (coming soon)
## Contributing
Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
## License
MIT License - see [LICENSE](LICENSE) file for details
## Acknowledgments
- Inspired by [Spector.js](https://github.com/BabylonJS/Spector.js)
- WebGL best practices from the [WebGL community](https://www.khronos.org/webgl/)
- Three.js integration patterns from the [Three.js](https://threejs.org/) ecosystem