CesiumGS
`CustomShaders`: make `FragmentInput` struct more consistent for `Model` and `VoxelPrimitive`
Feature
A CustomShader for a VoxelPrimitive uses an undocumented form of the FragmentInput struct.
Comparison to the FragmentInput struct used for Model
The FragmentInput struct for voxels differs from the FragmentInput struct used for a CustomShader attached to a Model in several key ways:
Metadata statistics
Statistics for voxel metadata are appended to the Metadata struct. For example, to access the minimum value of a metadata property, a user must use code like this:
float valMin = fragmentInput.metadata.statistics.${property}.min;
Since #10683, these statistics for Model have been moved to a top-level MetadataStatistics struct. We should also add a MetadataClass struct to contain the noData value, as was done for Model in #10520.
Attributes
Some standard attributes such as positionEC and normalMC (renamed as surfaceNormal) are hidden inside the voxel sub-struct. These should be moved to FragmentInput.attributes for consistency with Model.
Voxel-specific values
Some properties of the voxel sub-struct do not have direct parallels with Model. For example, travelDistance is useful for accurate opacity calculations. Others such as tileIndex and sampleIndex are conceptually similar to FeatureIds, but we may not want to use the same terms since FeatureId properties are aligned with specific glTF extensions that aren't mirrored in the 3DTILES_content_voxels extension.
What needs to change
Most of the required changes will be in processVoxelProperties.js and VoxelFS.glsl. Also the Custom Shader Guide will need to be updated for any properties that remain different for voxels.
These changes will break many existing voxel shaders. But the long-term benefits include:
- Simplified documentation
- Faster onboarding for new users of CesiumJS voxel rendering
- Easier maintenance of voxel code and docs
Some understandable confusion around this was reported in https://github.com/CesiumGS/cesium/issues/12124.