# Webglue Integration Guide
## Drop-in Replacement for `gl` Crate
Webglue can now be used as a drop-in replacement for the native `gl` crate in existing OpenGL applications.
### Setup
In your `Cargo.toml`, replace:
```toml
[dependencies]
gl = "0.14.0"
```
With:
```toml
[dependencies]
gl = { package = "webglue", path = "../path/to/webglue" }
```
Cargo's package renaming feature aliases `webglue` as `gl`, so all your existing code continues to work:
```rust
use gl::types::*;
unsafe {
gl::load_with(|symbol| window.get_proc_address(symbol) as *const _);
gl::GenBuffers(1, &mut vbo);
gl::BindBuffer(gl::ARRAY_BUFFER, vbo);
// ... all your existing GL code works!
}
```
### Architecture
**Flattened Module Structure**:
- Everything exported at crate root level (`webglue::GenBuffers`, `webglue::ARRAY_BUFFER`)
- When renamed as `gl`, becomes `gl::GenBuffers`, `gl::ARRAY_BUFFER`
- `types` and `constants` remain as public submodules for `gl::types::GLuint` compatibility
**For Demo/Internal Usage**:
```rust
// In demo/src/lib.rs
pub use webglue as gl; // Create module alias
// Now you can use:
crate::gl::GenBuffers(1, &mut vbo);
crate::gl::ARRAY_BUFFER
```
### Compatibility
#### ✅ Fully Supported (56 functions)
All core GL functions needed for 3D rendering:
- Buffers: GenBuffers, BindBuffer, BufferData, BufferSubData, DeleteBuffers
- VAOs: GenVertexArrays, BindVertexArray, EnableVertexAttribArray, VertexAttribPointer
- Shaders: CreateShader, ShaderSource, CompileShader, GetShaderiv, GetShaderInfoLog
- Programs: CreateProgram, AttachShader, LinkProgram, UseProgram, GetUniformLocation
- Uniforms: Uniform1f, Uniform2f, Uniform3f, Uniform4f, Uniform1i, UniformMatrix3fv, UniformMatrix4fv
- Textures: GenTextures, BindTexture, TexImage2D, TexParameteri, GenerateMipmap, TexSubImage2D
- Drawing: DrawArrays, DrawElements, DrawElementsInstanced
- State: Enable, Disable, Viewport, ClearColor, Clear, DepthMask, BlendFunc
#### ⚠️ Stubbed (no-op)
Functions that exist for compatibility but don't do anything:
- `load_with()` - No-op (glow context already initialized)
- Framebuffer objects - GenFramebuffers, BindFramebuffer, etc. (use canvas APIs instead)
- ReadPixels - Use browser `canvas.toDataURL()` instead
- PointSize - Use `gl_PointSize` in vertex shader (WebGL2 requirement)
#### ❌ Desktop-Only Constants
These constants are defined but may not work as expected in WebGL:
- `STACK_OVERFLOW`, `STACK_UNDERFLOW` - Desktop GL error codes
- `CONTEXT_PROFILE_MASK`, `CONTEXT_FLAGS` - Desktop GL context info
- `BGR`, `BGRA` - Desktop pixel formats (WebGL uses RGB/RGBA)
### Tested With
- ✅ **gltf-viewer-webgl** - Full GLTF 2.0 viewer, builds successfully
- ✅ **webglue demo** - 9 rendering samples with texture mapping
### Example: gltf-viewer Integration
**Before** (native `gl` crate):
```toml
[dependencies]
gl = "0.14.0"
glutin = "0.18.0"
```
**After** (webglue):
```toml
[dependencies]
gl = { package = "webglue", path = "../../webglue" }
glutin = "0.18.0"
```
**No source code changes required!** All 37 GL functions used by gltf-viewer are implemented.
### Building
```powershell
# Build webglue library
cd C:\build\webglue
cargo build --lib
# Build gltf-viewer with webglue
cd C:\build\rust\gltf-viewer-webgl
cargo build
# Build webglue demo (WASM)
cd C:\build\webglue\demo
npm run build # or wasm-pack build
```
### Next Steps
To create a GLTF loader demo in webglue:
1. **Add gltf crate to demo**:
```toml
[dependencies]
gltf = { version = "0.15", features = ["names"] }
image = "0.21"
```
2. **Create gltf module**:
```
demo/src/gltf/
mod.rs
loader.rs
primitive.rs
material.rs
```
3. **Implement basic loader**:
- Parse GLTF JSON
- Load buffer data
- Upload vertex/index buffers
- Load textures
- Render primitives
4. **Add to sample rotation**:
```rust
suite.add_sample(Box::new(GltfSample::new("models/Box.gltf")));
```
See `demo/docs/GLTF.md` for detailed implementation plan.