# webglue
**WebGL2 wrapper for Rust and WebAssembly**
[](LICENSE)
[](https://www.rust-lang.org)
[](https://webassembly.org/)
## Overview
**webglue** is a WebGL2 wrapper for Rust that compiles to WebAssembly, providing an OpenGL-like API for browser-based 3D graphics.
> ⚠️ **This crate is WASM-only** and must be compiled with `--target wasm32-unknown-unknown`.
Built on top of [`glow`](https://github.com/grovesNL/glow), webglue translates familiar OpenGL function calls into WebGL2 operations, with a handle registry to bridge between u32 IDs and glow's opaque handles.
### Key Features
- 🎯 **70+ WebGL2 functions** - Comprehensive rendering pipeline
- 🚀 **Instanced rendering** - DrawElementsInstanced for high-performance graphics
- 📐 **Matrix math library** - Perspective, lookAt, rotate, translate, scale operations
- 📦 **Optional GLTF support** - Load and render GLTF/GLB 3D models
- 🔄 **Handle-based registry** - Bridges u32 IDs ↔ glow's opaque WebGL handles
- ⚡ **Optimized builds** - ~105KB WASM (gzipped with LTO)
## Quick Start
### 1. Add to your `Cargo.toml`
```toml
[dependencies]
webglue = "0.1"
# Optional: Enable GLTF model loading
webglue = { version = "0.1", features = ["gltf"] }
```
### 2. Build for WebAssembly
```bash
cargo build --target wasm32-unknown-unknown --release
# Or use wasm-pack
wasm-pack build --target web --release
```
### 3. Basic Usage
```rust
use webglue as gl;
unsafe {
// Initialize once with WebGL2 context
gl::init_with_webgl2_context(webgl2_context);
// Create and bind buffer
let mut vbo = 0;
gl::GenBuffers(1, &mut vbo);
gl::BindBuffer(gl::ARRAY_BUFFER, vbo);
// Upload vertex data
gl::BufferData(
gl::ARRAY_BUFFER,
(vertices.len() * 4) as isize,
vertices.as_ptr() as *const _,
gl::STATIC_DRAW
);
// Setup vertex attributes
gl::VertexAttribPointer(0, 3, gl::FLOAT, gl::FALSE, 0, std::ptr::null());
gl::EnableVertexAttribArray(0);
// Draw
gl::DrawArrays(gl::TRIANGLES, 0, vertex_count as i32);
}
```
## Implemented WebGL2 Functions
### Buffer Management (5)
- `GenBuffers`, `DeleteBuffers`, `BindBuffer`, `BufferData`, `BufferSubData`
### Vertex Arrays (7)
- `GenVertexArrays`, `DeleteVertexArrays`, `BindVertexArray`
- `EnableVertexAttribArray`, `DisableVertexAttribArray`
- `VertexAttribPointer`, `VertexAttribDivisor`
### Shaders & Programs (13)
- `CreateShader`, `DeleteShader`, `ShaderSource`, `CompileShader`
- `CreateProgram`, `DeleteProgram`, `AttachShader`, `LinkProgram`, `UseProgram`
- `GetShaderiv`, `GetShaderInfoLog`, `GetProgramiv`, `GetProgramInfoLog`
### Uniforms (10)
- `GetUniformLocation`
- `Uniform1f`, `Uniform1i`, `Uniform2f`, `Uniform3f`, `Uniform4f`
- `Uniform3fv`, `Uniform4fv`
- `UniformMatrix3fv`, `UniformMatrix4fv`
### Textures (9)
- `GenTextures`, `DeleteTextures`, `BindTexture`, `ActiveTexture`
- `TexImage2D`, `TexSubImage2D`, `TexParameteri`
- `GenerateMipmap`, `PixelStorei`
### Drawing (3)
- `DrawArrays`, `DrawElements`, `DrawElementsInstanced` ⚡
### Framebuffers & Renderbuffers (6)
- `GenFramebuffers`, `BindFramebuffer`, `FramebufferTexture2D`
- `GenRenderbuffers`, `BindRenderbuffer`, `RenderbufferStorage`
### State Management (11)
- `Enable`, `Disable`, `Viewport`, `Clear`, `ClearColor`
- `DepthMask`, `BlendFunc`, `BlendFuncSeparate`, `Finish`
- `ReadPixels`, `PointSize` (stub)
### Queries (5)
- `GetError`, `GetGraphicsResetStatus`, `GetIntegerv`, `GetString`, `GetStringi`
**Total: 70+ functions** ✅
## Architecture
```
┌──────────────────────────────────────┐
│ Your Rust/WASM Application │
│ (OpenGL-style function calls) │
└────────────────┬─────────────────────┘
│
┌──────▼─────────┐
│ webglue │
│ wrapper.rs │
└──────┬─────────┘
│
┌──────▼─────────┐
│ Handle Registry│
│ (u32 ↔ Handle) │
└──────┬─────────┘
│
┌──────▼─────────┐
│ glow │
│ (Rust→WebGL) │
└──────┬─────────┘
│
┌──────▼─────────┐
│ WebGL2 │
│ (Browser) │
└────────────────┘
```
### Why Handle Registry?
WebGL via `glow` uses opaque handles (`glow::Buffer`, `glow::Program`, etc.), not u32 IDs like desktop OpenGL. The registry:
- **Translates** u32 IDs ↔ opaque glow handles
- **Maintains** OpenGL-style API compatibility
- **Uses** `slab` for efficient O(1) lookups
- **Minimal overhead** - direct index-to-handle mapping
## Math Library
Built-in 4x4 matrix operations for 3D graphics:
```rust
use webglue::math::*;
// Projection matrix
let proj = perspective(45.0_f32.to_radians(), aspect_ratio, 0.1, 100.0);
// View matrix
let view = look_at(
&[0.0, 2.0, 5.0], // camera position
&[0.0, 0.0, 0.0], // look at target
&[0.0, 1.0, 0.0], // up vector
);
// Model transformations
let model = Mat4::identity()
.rotate_y(angle)
.translate(&[x, y, z])
.scale(&[sx, sy, sz]);
// Combined MVP matrix
let mvp = proj * view * model;
// Upload to shader uniform
unsafe {
gl::UniformMatrix4fv(mvp_loc, 1, gl::FALSE, mvp.as_ptr());
}
```
Available operations:
- `perspective()`, `orthographic()` - Projection matrices
- `look_at()` - View matrix from camera parameters
- `Mat4::identity()`, `translate()`, `rotate_x/y/z()`, `scale()` - Transforms
- Matrix multiplication with `*` operator
## GLTF Model Loading
With the `gltf` feature enabled, you can load and render 3D models:
```rust
use webglue::gltf_model::GltfModel;
// Load GLTF model from URL
let model = GltfModel::load_from_url("models/scene.gltf").await?;
// Render in your draw loop
unsafe {
model.render();
}
```
Supports:
- GLTF 2.0 and GLB binary format
- Embedded textures and images
- Multiple meshes and materials
- Extensions: `KHR_lights_punctual`, `extras`, `names`
## Performance
WebGL2 instanced rendering provides massive performance gains for repeated geometry:
| Individual DrawArrays | 1,000 | 1,000 | ~15-30 FPS |
| **DrawElementsInstanced** | **1** | **1,000** | **60 FPS** |
| **DrawElementsInstanced** | **1** | **10,000** | **60 FPS** |
**Speedup: 100-500x** for scenes with many similar objects 🚀
## Demo & Examples
The repository includes a comprehensive Vite-based demo application in `demo/`:
```bash
cd demo
npm install
npm run dev
```
**Live Demo**: Opens interactive showcase with multiple samples:
- **Textured Sphere** - Earth texture mapping with UV coordinates
- **Textured Cube** - 3D cube with image textures
- **Colored Cube** - RGB vertex colors
- **Instanced Rendering** - 1000+ objects in a single draw call
- **GLTF Models** - Load and render 3D scenes (Box, FlightHelmet, Head)
- **Primitives** - Sphere, cone geometry generation
- **Matrix Transforms** - Rotation, translation, scaling
- **Blend Modes** - BlendFunc and BlendFuncSeparate demos
## Building
### Library Build (WASM target required)
```bash
# Build library for WebAssembly
cargo build --target wasm32-unknown-unknown --release
# With GLTF feature
cargo build --target wasm32-unknown-unknown --release --features gltf
# Run unit tests (on host target)
cargo test --lib
```
### Using wasm-pack (Recommended)
```bash
# Install wasm-pack
cargo install wasm-pack
# Build for web
wasm-pack build --target web --release --out-dir pkg
# The pkg/ directory is ready to import in JavaScript:
# import init, * as wasm from './pkg/webglue.js';
```
### Size Optimization
Release builds are optimized for size:
- **LTO enabled** - Link-time optimization
- **Single codegen unit** - Maximum optimization
- **Result**: ~105KB WASM (gzipped)
Cargo.toml configuration:
```toml
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
```
## Version Status
| `glow` | 0.16 | 0.16.0 | ✅ Up to date |
| `slab` | 0.4 | 0.4.11 | ✅ Up to date |
| `gltf` | 1.4 | 1.4.1 | ⚠️ Consider updating |
| `wasm-bindgen` | 0.2 | 0.2.104 | ⚠️ Consider updating |
| `web-sys` | 0.3 | 0.3.81 | ⚠️ Consider updating |
> Run `cargo update` to get latest compatible versions within semver ranges.
## License
Copyright © 2025 Top-5
Licensed under the Apache License, Version 2.0 ([LICENSE](LICENSE) or http://www.apache.org/licenses/LICENSE-2.0)
## Contributing
Contributions welcome! Priority areas:
- 🔧 Update to latest dependency versions (gltf 1.4.1, wasm-bindgen 0.2.104, etc.)
- 📚 More WebGL2 functions (additional state management, queries)
- 🧮 Extended math utilities (quaternions, frustum culling)
- 📦 More GLTF features (animations, skinning)
- 📖 Documentation and examples
- 🧪 Test coverage improvements
## Credits
Built on top of excellent Rust crates:
- [`glow`](https://github.com/grovesNL/glow) - OpenGL/WebGL bindings
- [`gltf`](https://github.com/gltf-rs/gltf) - GLTF 2.0 loader
- [`slab`](https://github.com/tokio-rs/slab) - Efficient handle registry
- [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) - Rust/WASM/JS glue