WebGL Inspector is a tool inspired by gDEBugger and PIX with the goal of making the development of advanced WebGL applications easier. What Firebug and Developer Tools are to HTML/JS, WebGL Inspector is to WebGL.
- Embed in an existing application with a single
<script>include - Use as an extension without changing target code
- Capture entire frames of GL activity
- Annotated call log with redundant call warnings
- Ability to step through all calls in a frame incrementally (back/forward/jump/etc)
- Pixel history - see all draw calls that contributed to a pixel + blending information
- Non-destructive to host page - everything happens in a separate GL context
- Internal GL state display
- Resource information (textures/buffers/programs/shaders)
- Performance tuning options and statistics
There are currently two ways to use the inspector - one is to directly embed it in your GL application (should work in all browsers that support WebGL), and the other is to use one of the supported extensions.
Before starting, run core/buildextensions.sh - this will cat all required files together and copy them into the right places. Note that
this is not required when using the debug variants.
Include a single script: <script src="core/embed.js"></script> No other changes should be required!
If you want to debug the inspector, before the script include set gliEmbedDebug = true;:
<script>
var gliEmbedDebug = true;
</script>
<script src="core/embed.js"></script>
This will use the un-cat'ed script/css files, making debugging easier.
LIVE: Instead of grabbing the code, building, and embedding, you can include the script directly from the sample site. This version will change whenever I release a new version. <script src="http://benvanik.github.com/WebGL-Inspector/core/embed.js"></script>
Note: when running the debug version require.js is used to load the inspector. This can have
issues for when the inspector gets a chance to wrap HTMLCanvasContext.getContext and when code tries to use it.
The first thing to try is make sure you code waits for window.onload before creating a webgl context. If that doesn't work
you can also wait for gliready
window.addEventListener('gliready', runYourWebGLCode);
If your app also uses require.js you need to make your app dependent on the inspector like
this. One example would be to do this. Assume your program before used data-main as in
<script data-main="myApp.js" src="require.js">
Remove the data-main part and change it to something like
<script "myApp.js" src="require.js">
<script>
require(['../../core/gli'], function() {
require.config({
baseUrl: "/path/to/appfolder",
});
require(['twgl-amd'], function() {
});
});
</script>
Note: This is only needed for running the inspector in debug mode to debug the inspector itself.
- Navigate to chrome://extensions
- Click 'load unpacked extension...' and select the extensions/chrome/ directory
- If you will be trying to inspect file:// pages, make sure to check 'Allow access to file URLs'
- Open a page with WebGL content and click the 'GL' icon in the top right of the address bar (click again to disable)
DEBUGGING: If you want to debug the inspector code, instead load the extension from core/ - this will use the non-cat'ed files and makes things much easier when navigating source. You'll also be able to just reload pages when you make changes to the extension (although sometimes the CSS requires a full browser restart to update).
Download WebGL Inspector from Mozilla AMO or build manually:
cd core && ./buildextensions.sh- Open
core/extensions/firefox/webglinspector.xpiin Firefox.
DEBUGGING
cd core/extensions/firefoxmake runorPROFILE=/path/to/dev/profile make run
- Open the Extension Builder
- Add existing extension
- Select extensions/safari/webglinspector.safariextension
- Open a page with WebGL content and click the 'GL' icon in the top left of the toolbar (click again to disable)
DEBUGGING: There is currently no debug version of the extension - since Chromium is so similar it's best to just use that.
Due to the way WebGL implicitly ends frames, accurately determining when a host application has finished is tricky. To ensure frame captures are exactly what they should be there is an extension that can be used to tell the inspector when you are done.
Query the extension - it will only exist when the inspector is attached: var glext_ft = gl.getExtension("GLI_frame_terminator");
At the end of your frame, call the termination method:
if (glext_ft) {
glext_ft.frameTerminator();
}Do this if you are consistently seeing multiple frames getting captured at the same time.
Included in the repository is the Learning WebGL Lesson 05 under samples/lesson05/. embedded.html shows the inspector
inlined on the page using the single <script> include. Diff the file against original.html (or look for 'WebGL Inspector' comments) to see what was changed.
Once you have an extension installed, here are some fun demos to test it with:
In no particular order, here are some of the major features I'd like to see added:
- Call statistics (with pretty graphs/etc)
- Save traces/resources/buffer snapshots/etc
- Serialization of call stream (could do remote debugging/save and replay/etc)
- Editing of buffers/shaders in replay
- Editing of state/call history (tweak arguments/etc)
On top of those there are plenty of little things (UI tweaks, etc) that would be helpful. For example, global key bindings would make stepping better.
Some crazier things may be possible in the future, too. For example, if the serialization was implemented it'd be possible to do remote debugging/playback of scenes from Android/iOS/etc devices (once they support WebGL), as well as build test frameworks for WebGL content.