metal: pass API validation with 3D terrain on and off - #4556
Open
AndrewN81 wants to merge 2 commits into
Open
Conversation
Two validation aborts under Xcode's Metal API Validation (the default for a Run scheme), both invisible without validation because nothing is sampled or the mismatch happens to work: 1. The symbol, circle and fill-extrusion shaders declare a DEM sampler (and the symbol shader a terrain-depth sampler) unconditionally, but the layer tweakers only bind them when a RenderTerrain exists. On a flat map every symbol draw hit "missing sampler binding". Vulkan already binds a dummy texture in that gap; add gfx::Context::getPlaceholderTexture2D (a 1x1 zero texture) and bind it in the three tweakers when terrain is off. 2. ShaderProgram::getRenderPipelineState cached pipeline states by the caller's hash of colour mode + vertex layout only, so a state built for the BGRA8 + stencil screen was reused for RGBA8 offscreen targets without a stencil (terrain drape targets, hillshade prepare targets): "pipeline's pixelFormat does not match the framebuffer's". Fold the renderable's colour, depth and stencil formats into the cache key. Verified on the iOS simulator with MTL_DEBUG_LAYER=1: flat map and draped terrain both run with zero validation messages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
github-actions
Bot
added
the
core
for more information, see https://pre-commit.ci
AndrewN81
marked this pull request as ready for review
September 5, 2026 10:24
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two Metal API validation failures with the terrain-3d branch, one with terrain off and one with it on. Xcode's Run scheme enables Metal API Validation by default, so with this branch any app hits one of them on launch (terrain off) or on the first draped frame (terrain on).
missing sampler binding at index N for demSampler/depthSampler.gfx::Context::getPlaceholderTexture2D()now provides a 1x1 texture that the tweakers bind whenparameters.terrainis null (the shaders never sample it,dem_enabled/depth_enabledare 0).mtl::ShaderProgram::getRenderPipelineStatecached states keyed only on the colour mode and vertex layout, so a state created for the BGRA8 screen was reused for the RGBA8 drape and hillshade render targets (Set Render Pipeline State Validation ... BGRA8Unorm vs RGBA8Unorm, and a stencil format mismatch). The cache key now folds in the colour, depth and stencil attachment formats.How it was verified
SIMCTL_CHILD_MTL_DEBUG_LAYER=1 xcrun simctl launch <udid> <bundle>; both are gone with this change, with terrain on and off.Notes
Written with AI assistance (Claude), reviewed and tested by me before opening this PR, per MapLibre's AI policy.