stride3d/stride · error · NotSupportedException

Static Samplers can only have opaque black, opaque white or…

Error message

Static Samplers can only have opaque black, opaque white or transparent black as border color.

What it means

D3D12 static samplers may only use the fixed border colors the API can encode (OpaqueBlack, OpaqueWhite, TransparentBlack). When the backend tries to map a sampler's BorderColor to a StaticBorderColor, any other color hits the final throw of NotSupportedException.

Solutions

Change the sampler border color to one of: OpaqueBlack, OpaqueWhite, or TransparentBlack
Move the sampler out of static samplers into a dynamically-bound sampler descriptor if a custom border color is required
Default to OpaqueBlack/TransparentBlack unless a specific border look is needed

Example fix

// before
var sampler = new SamplerStateDescription { BorderColor = new Color4(1f, 0f, 0f, 1f) };
// after
var sampler = new SamplerStateDescription { BorderColor = Color4.TransparentBlack };

Defensive patterns

Strategy: validation

Validate before calling

if (sampler.BorderColor is not (Color4.Black or Color4.White or Color4.TransparentBlack)) throw new InvalidOperationException("Static sampler border color must be opaque black/white or transparent black");

Type guard

bool HasStaticBorderColor(Color4 c) => c.Equals(Color4.Black) || c.Equals(Color4.White) || c.Equals(Color4.TransparentBlack);

Try / catch

try { state = PipelineState.New(device, desc); } catch (NotSupportedException) { /* non-static border color */ throw; }

Prevention

Use only the three D3D12 static border colors in sampler descriptions
For custom border colors, use dynamically bound samplers instead of static samplers

When it happens

Trigger: SamplerStateDescription with a custom BorderColor (e.g. Color4(1,0,0,1) or any non-black/white value) included in a PipelineStateDescription's static samplers.

Common situations: Clamp/border sampling with a tinted border color configured by artists; copying sampler settings from an engine/backend that supports arbitrary border colors.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/b09896baad22bf82. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Graphics/Direct3D12/PipelineState.Direct3D12.cs:692

            //
            // Converts a Color4 to its corresponding StaticBorderColor for a Sampler's border color.
            //
            static StaticBorderColor ConvertToStaticBorderColor(Color4 color)
            {
                if (color == Color4.Black)
                {
                    return StaticBorderColor.OpaqueBlack;
                }
                else if (color == Color4.White)
                {
                    return StaticBorderColor.OpaqueWhite;
                }
                else if (color == Color4.TransparentBlack)
                {
                    return StaticBorderColor.TransparentBlack;
                }

                throw new NotSupportedException("Static Samplers can only have opaque black, opaque white or transparent black as border color.");
            }

            //
            // Returns the Direct3D 12 Shader Visibility for a Stride's ShaderStage.
            //
            static ShaderVisibility GetShaderVisibilityForStage(ShaderStage stage)
            {
                return stage switch
                {
                    ShaderStage.Vertex => ShaderVisibility.Vertex,
                    ShaderStage.Hull => ShaderVisibility.Hull,
                    ShaderStage.Domain => ShaderVisibility.Domain,
                    ShaderStage.Geometry => ShaderVisibility.Geometry,
                    ShaderStage.Pixel => ShaderVisibility.Pixel,
                    ShaderStage.Compute => ShaderVisibility.All,

                    _ => throw new ArgumentOutOfRangeException(nameof(stage), stage, "Invalid ShaderStage.")
                };

View on GitHub (pinned to 96fad776d2)