stride3d/stride · error · ArgumentOutOfRangeException

Last blurriest level must have a CoC of 1.0!

Error message

Last blurriest level must have a CoC of 1.0!

What it means

The last (blurriest) entry in levelCoCValues must be exactly 1.0, since it defines the full circle-of-confusion level that anchors the blur pyramid. SetupTechnique throws ArgumentOutOfRangeException when the final CoC value differs from 1f.

Solutions

1. Set the last element of levelCoCValues to 1f
2. Normalize the array so the largest CoC becomes 1.0
3. Use null/default levels if custom pyramid configuration is not needed

Example fix

// before
dof.LevelCoCValues = new[] { 0.25f, 0.5f, 0.75f };
// after
dof.LevelCoCValues = new[] { 0.25f, 0.5f, 1.0f };

cocValues[cocValues.Length - 1] = 1f; // enforce blurriest level = 1.0

bool LastCoCIsOne(float[] coc) => coc == null || coc.Length == 0 || Math.Abs(coc[coc.Length - 1] - 1f) < float.Epsilon;

try { dof.SetupTechnique(); } catch (ArgumentOutOfRangeException) { dof.LevelCoCValues[^1] = 1f; dof.SetupTechnique(); }

When it happens

Trigger: Setting levelCoCValues whose last element is not 1.0 (e.g. {0.5f, 0.8f, 0.9f}) and calling SetupTechnique or rendering.

Common situations: Hand-tuned CoC values scaled below 1.0; computing values from aperture formulas that don't normalize the maximum to 1; copying configs and tweaking the last value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• DoF configuration needs at least one blur level!
• levelCoCValues and levelDownscaleFactors must be arrays of…
• You cannot provide downscale factors without CoC values…
• Radius cannot be < 0
• Radius cannot be < 1

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

Appendix: source

Thrown at sources/engine/Stride.Rendering/Rendering/Images/DepthOfField/DepthOfField.cs:302

            }

            if (levelCoCValues != null && levelDownscaleFactors != null)
            {
                if (levelCoCValues.Length != levelDownscaleFactors.Length)
                {
                    throw new ArgumentOutOfRangeException("levelCoCValues and levelDownscaleFactors must be arrays of the same size!");
                }
            }

            if (levelCoCValues != null && levelCoCValues.Length == 0)
            {
                if (levelCoCValues.Length == 0)
                {
                    throw new ArgumentOutOfRangeException("DoF configuration needs at least one blur level!");
                }
                if (levelCoCValues[levelCoCValues.Length - 1] != 1f)
                {
                    throw new ArgumentOutOfRangeException("Last blurriest level must have a CoC of 1.0!");
                }
            }

            // Default values: 1 original image and 1 blur level
            int levelCount = 2;
            if (levelCoCValues != null)
            {
                levelCount = levelCoCValues.Length + 1;
            }

            CleanupEffects();
            cocLevels.Clear();
            combineShaderCocLevelValues = new float[levelCount];
            
            // Special case: level 0 is always our original image
            cocLevels.Add(new CoCLevelConfig { CoCValue = 0f, DownscaleFactor = 0 });
            combineShaderCocLevelValues[0] = 0f;

View on GitHub (pinned to 96fad776d2)