How khronosgroup/gltf-sample-viewer works
1. Project type and runtime
- This is a client-side web application for viewing glTF 2.0 assets in the browser.
- It runs entirely in the browser on WebGL 2.0, with no application backend in this repo.
2. Top-level composition
- index.html is the shell page.
- main.js at the repo root is the browser entry point.
- src/main.js appears to be the real application bootstrap, with main.js likely forwarding into the source build pipeline.
- The app is split into a UI layer, a state/logic layer, and a renderer integration layer.
3. Rendering subsystem
- The actual 3D rendering is delegated to the glTF-Sample-Renderer submodule.
- That submodule is the core dependency for loading and drawing models, materials, animations, lighting, compression formats, and extensions.
- This repo mostly wraps and configures that renderer rather than implementing its own rendering engine.
4. UI subsystem
- src/ui/ui.js and src/ui/sass.scss define the in-browser control surface.
- The UI provides model selection, drag-and-drop loading, lighting/tone mapping controls, animation toggles, material variants, validator feedback, stats, downloads, and debug channels.
- Styling is isolated in Sass, which suggests the viewer UI is a distinct presentation layer over the renderer.
5. State and behavior subsystem
- src/logic/uimodel.js is the central state/interaction model for the viewer.
- It likely mediates between user actions and renderer behavior: selected model, camera state, animation enablement, material variant choice, extension/debug toggles, and UI visibility.
- This is the main boundary between UI events and rendering configuration.
6. Asset/model path resolution
- src/model_path_provider.js is a dedicated helper for resolving model and asset URLs.
- Given the README’s support for sample assets, custom URLs, and drag-and-drop files, this module likely abstracts where model content comes from and how it is addressed.
- It forms an important boundary between the viewer and external asset sources.
7. Input and data-flow path
- User inputs come from three main sources: UI controls, drag-and-drop files, and URL parameters.
- Those inputs flow into the UI model/state layer, which then configures the renderer and loads the appropriate glTF/HDR resources.
- The app also supports externally hosted content through URL parameters such as model, camera offsets, and noUI.
8. Supported content and external dependencies
- The viewer is designed around the glTF ecosystem and supports many Khronos/Vendor extensions, including compression, lighting, material variants, basis textures, and mesh instancing.
- It also supports HDR environment maps, so the rendering pipeline handles both model content and scene lighting inputs.
- Validation support is integrated into the UX, implying the viewer can surface glTF validation results alongside rendering.
9. Build and packaging pipeline
- rollup.config.js drives bundling for the browser.
- package.json plus package-lock.json define the frontend toolchain and dependencies.
- The output is a static dist directory, consistent with deployment to ordinary static hosting.
10. Deployment and hosting
- The GitHub Actions workflow in .github/workflows/Publish_to_Github_Pages.yml publishes the built app to GitHub Pages.
- This repository therefore has a simple deploy model: build in CI, publish static assets, serve directly from a CDN/static host.
11. Repository organization
- assets/ contains figures, images, and UI resources used by the viewer and documentation.
- glTF-Sample-Renderer/ is intentionally separated as vendored source via git submodule.
- The repo is focused on the viewer wrapper, while the renderer engine remains upstreamed.
12. Architecture summary for diagramming
- A good diagram would show: browser shell/index → app bootstrap → UI/state layer → sample renderer submodule → WebGL2 canvas, with side inputs from URL parameters, drag-and-drop files, and model path resolution.
- A separate deployment lane should show Rollup build → dist → GitHub Pages.
Main entry points: uimodel.js UI model · glTF-Sample-Renderer Sample Renderer · main.js App bootstrap · ui.js UI controls
Components 16
Viewer app
Browser-side viewer shell, UI, and state orchestration.
- index.html · Browser document that hosts the viewer.
index.html - main.js · Top-level entry that forwards into the application bundle.
main.js - App bootstrap · Initial application wiring and launch sequence.
src/main.js - UI controls · Viewer control surface for loading, toggles, stats, and debug actions.
src/ui/ui.js - UI styles · Presentation styling for the in-browser viewer.
src/ui/sass.scss - UI model · Central state and interaction boundary between controls and rendering.
src/logic/uimodel.js - Path provider · Resolves model and asset locations for local, remote, and dropped content.
src/model_path_provider.js - URL params · Query-driven viewer configuration and external content selection.
- Drag and drop · Local file input path for loading glTF assets in the browser.
- WebGL 2.0 · Client-side GPU runtime used to render the scene.
- Model assets · glTF, HDR, textures, and related scene resources consumed by the viewer.
Renderer vendor
Vendored glTF rendering engine used by the viewer.
- Sample Renderer · Vendored glTF rendering engine for loading, shading, and animation.
glTF-Sample-Renderer - Extensions · Compression, lighting, materials, variants, and other supported glTF extensions.
glTF-Sample-Renderer
Build and publish
Frontend bundling and static hosting pipeline.
- Rollup · Build pipeline that packages the browser application.
rollup.config.js - dist · Generated static site artifacts produced by the build.
- GitHub Pages · Static deployment target for the published viewer.
.github/workflows/Publish_to_Github_Pages.yml
Connections 18
- index.html → main.js: loads · The shell page loads the browser entry point.
- main.js → App bootstrap: starts · The entry forwards into the application bootstrap.
- App bootstrap → UI controls: mounts · Bootstrap initializes the viewer controls.
- App bootstrap → UI model: creates · Bootstrap creates the central UI and interaction model.
- UI controls → UI model: events · Control interactions update viewer state.
- UI model → Path provider: resolves · State uses asset resolution to locate model and resource inputs.
- URL params → UI model: configures · Query parameters seed viewer configuration.
- Drag and drop → Path provider: provides · Dropped files are normalized into loadable asset locations.
- Path provider → Model assets: locates · The resolver points the viewer at model and scene resources.
- UI model → Sample Renderer: configures · Viewer state drives renderer settings and scene setup.
- Sample Renderer → WebGL 2.0: renders on · The renderer executes against the browser WebGL runtime.
- Sample Renderer → Extensions: supports · Core renderer capabilities include glTF extensions and material features.
- Model assets → Sample Renderer: loads · Scene resources are consumed by the renderer.
- UI controls → UI styles: styled by · The control surface is separated from its Sass styling.
- Rollup → dist: builds · Rollup emits the static browser bundle.
- dist → GitHub Pages: publishes · Built artifacts are deployed as a static site.
- App bootstrap → Sample Renderer: wires · Application startup connects the viewer to the vendored renderer.
- UI model → UI controls: reflects · State changes feed back into the UI.