Debug Context

From WebGL Public Wiki
Jump to navigation Jump to search

To ease development using the WebGL API without degrading performance, a "debug context" is proposed.

The proposal does not require support for the debug context (it is non-normative), but strongly recommends it wherever resources are not highly constrained (e.g. in web browsers running on a desktop OS).

Getting the Debug Context

The debug context is accessed by calling a Canvas Element's getContext operation with the string "3d-debug". If the debug context is not available, this call will return null. For ease of use, a developer option is recommended that will cause a Canvas Element to return the debug context when getContext is called with the string "3d".

Error Handling

Wherever the GL specification requires setting the error flag, the debug context should provide immediate feedback that an error has occurred and details about the error (minimally the GL error code and it's descriptive string). If a stepping debugger is available, it is encouraged that execution immediately halt on return of the operation that caused the error, entering the debugger.

GL ARB Debug Context Discussion

The GL ARB has discussed debug contexts as a part of the GL Ecosystem. Our recommended debug context support should be consistent with the ARB's plans for ease of implementation and to meet developer expectations.

Jon Leech provided the following link for reference: [1]

Implementation Dependent Behavior

While the 3D Web group has generally agreed that implementation defined behavior is undesirable, eliminating all such behavior may prove difficult. Implementors of a debug context are encouraged to detect and log uses of implementation dependent behavior wherever possible.

Debug Utilities

Certain additional Context operations may prove useful when debugging, such as listing all Objects of a certain type or predefined state logging functions. Recommended operations will be listed explicitly to encourage consistency between debug context implementations.

Resource Management

Utilities to track and examine resource usage are encouraged. The 3D Web working group has not yet determined if inaccessible graphics resources will be automatically recycled, preventing resource allocation failure due to "leaks". If resource recycling is not automatic, debug context implementors will be encouraged to add leak detection and reporting wherever possible.