how to manage what shader builtins are available in CustomShader?
- Dominant language
- JavaScript
- Stars
- 15.8k
- Forks
- 3.9k
- Avg merge
- 4d 6h
- Merged PRs (30d)
- 34
Description
While working on [this sandcastle](http://localhost:8080/Apps/Sandcastle/index.html#c=nVVtb9s2EP4rhPdhcuFSSrMCteMGS91mCxA3Qe11Xwy4tHSSiFKkyhcn7tD/viMpOZrbYcAAW+Idn3sl71GupLFkz+EBNHlNJDyQBRjuGvox6JLNKA/yQknLuAS9GY0vNnIj82DZKsMtVxJtO7sF0xZXTJ7TUqvmLVQawCTPp9mE/IL/l5m3j9aNKkAsmdX88cnBWjNpSqUbQ4EZ+15pW//RrtU1f4TiWrMGkj7qMJPcGauaVc2K00oWg53kr40kRPCqtlxWSx9/1uNuh1p6/+bDxGP3gPU8Rus1PNoZ+RTUihfd3hL7knwMyxvZOmynCe8J4VKhmH9ttqHSiLlzNoLiYkxCSuSooK3i0q74V8AyXtHswm9/849PIaFSs6oBRJymlKZkXXND8MfIzlUTckNMrZwo5M+W1GwPxCrCioJYDyugxPPEHLvWIdY7NJRS7+2nbv/3q9X2/d2H5dXtyje7q7xPItR+3Qmx+vJfqsdzBs2ZIE23OFaOia8ASG1ta2ZpCpI+8M+8hYIzqnSVeildK42BmdgyWWxbJaKQK6ULLtGjib5KoZjFOiMYO/iCZuRZyKLluEgCIOmSpCUw6zTcFOZpuc3GJCUvpjTc1CenfdD/5/TMOz0bOMU2nBOtLOaOHr2UxA1CcmWSvoTxhBjs8UDMaDbpkc9P9k4sh1C/jo8zmkVlnJ/uCCSOHBb3UIMc9i/r0t1Dft5hMlR7MfHR+q500UKyR934e+PlAq27sp/1DjvYMRcnkQCs8+cqDvG6avjiuAZDHEaoSKv53ru4ur+ZhIOIno6tDTeMRuU7H/IJcwy7XFyc4E0LuRNM9wVmdPrK1zUNrXs5HZ8aaOWqWoIxvlP0fDCrG/ltSE9hBLzbQKvU5CCBYhENEtkeDMWxTDoeCvzz7rHFCH6qMIon0t+ELSN7Vbiakc0oXWG2Jn3LLEuDjUk96Fb5MU7vPYsshHLFn9zW91qhP3u4ski2O4fjklZiff2fKOqDbUbhEg3YOshDxvXVxnIDimpgxQHdNdwAtXilktLJPHwpkoDohr9rR46srhktxWGt3igncaSrVVuDhoimu38oJz1zFE4z73TmTyckFZqOj9FkNDf2IOCyv/+/8qbFS0WcFgmlqYWmFZ430p3LP4OluTH98c7Toem84HvCi9c/+BSSXDBjcKd0QnjK3owu5ynivzNFgvD53+EnQ7CDh9Vnl7dRiYw7T1H8saVVSuyYPvH8Nw) from #10181, I realized that I was leaking a couple builtin variables:
1. The `czm_pi` constant
2. the `czm_normal` matrix for transforming from model -> eye space.
3. In other custom shaders I've made in the past, I've found the `czm_HSBToRGB()` quite useful.
These details are quite useful to have available to the user when writing shaders, as it saves effort. However, they are internal details that we want to be careful about to keep the API surface area small.
Do we:
1. Choose a set of essential uniforms/functions and document them as a public part of the shader API?
2. Disallow `czm_` builtins since they're private?
3. Or just be clear in the custom shader documentation that builtins are "use at your own risk"?
Contributor guide
Research direction
Start with the sandcastle linked from #10181 and the CustomShader behavior described here. Compare the exposed czm_pi, czm_normal, and czm_HSBToRGB builtins with the goal of keeping the shader API small. Done requires a decided policy for public versus private builtins and corresponding guidance or behavior.
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