CesiumGS / CesiumGS/cesium

Make it easier to debug custom shader compile errors

Open
#10,256 2 comments 1 reaction 0 assignees View on GitHub
category - model/gltf
Dominant language
JavaScript
Stars
15.7k
Forks
3.9k
Avg merge
4d 6h
Merged PRs (30d)
34

Description

Right now, the way I debug compilation errors for a custom shader is putting a breakpoint in `ShaderProgram.createAndLinkProgram()` on one of the lines that throw `DeveloperError`, and then inspect the variables `vsSource` and `fsSource` which contain the complete shader text (custom shader + ModelExperimental shader code + CesiumJS builtin-stuff). But this is cumbersome and might be confusing to explain.

The tricky thing is the shader code is built in stages:

* `CustomShader` only has the code the user added
* `ModelExperimental` has a `ShaderBuilder` object when creating draw commands. This contains the complete shader, of which the custom shader is a small portion. This is usually the code I want to look at when debugging since it has more context about attributes and structs in the shader.
* the draw command has the `ShaderProgram` which has the full shader (ModelExperimental code + built in renderer code)

It would be great to make some of these more accessible for debugging. Some ideas:

1. Perhaps the easiest, instead of ShaderProgram throwing a `DeveloperError`, maybe it could throw a new `ShaderCompilationError` that includes the vertex and fragment text.
2. Or just `console.error` with the shader text
3. the `ShaderBuilder` could certainly have a method like `getFullFragmentShaderText()` that combines the text like it does when building the `ShaderProgram`, but returns the string. The only tricky part is how would the user access the shader builder, as this is pretty deep in the private API.
4. a similar method could be used for the `ShaderProgram`, but again it would be cumbersome to access and would be exposing more private API.

I'm starting to like the sound of 1) then the user could catch the error and handle it as desired.

Contributor guide

Open the contributing guide

Research direction

Start at ShaderProgram.createAndLinkProgram() and trace how CustomShader, ModelExperimental, ShaderBuilder, and the draw command build vertex and fragment source. Compare the proposed ShaderCompilationError and shader-access approaches; done means selecting and implementing a clear debugging interface that exposes the relevant generated shader text without requiring private-object inspection.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
computer-graphics
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.