stride3d/stride · error · ArgumentOutOfRangeException

DoF configuration needs at least one blur level!

Error message

DoF configuration needs at least one blur level!

What it means

DepthOfField.SetupTechnique requires at least one entry in levelCoCValues; an empty array provides no blur level configuration and throws ArgumentOutOfRangeException. The multi-level DoF pipeline cannot be built without any level definitions.

Solutions

1. Assign a non-empty CoC array (last value must be 1.0)
2. Set levelCoCValues to null to fall back to the default 2-level configuration
3. Fix the generating code so it produces at least one level

Example fix

// before
dof.LevelCoCValues = collectedLevels.ToArray(); // empty
// after
var levels = collectedLevels.ToArray();
dof.LevelCoCValues = levels.Length > 0 ? levels : null; // null = defaults

if (cocValues != null && cocValues.Length == 0) cocValues = null; // null = use defaults

bool HasAtLeastOneLevel(float[] coc) => coc == null || coc.Length > 0;

try { dof.SetupTechnique(); } catch (ArgumentOutOfRangeException) { dof.LevelCoCValues = null; dof.SetupTechnique(); }

When it happens

Trigger: Assigning an empty array (new float[0]) to levelCoCValues, then calling SetupTechnique or rendering.

Common situations: Building level arrays programmatically where a filter produced zero elements; clearing the array intending to reset to defaults but the non-null empty array still triggers validation.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Last blurriest level must have a CoC of 1.0!
• 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/56f222d6050cdf3d. Report an issue: GitHub.

Appendix: source

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

            // Sanity checks
            if (levelCoCValues == null && levelDownscaleFactors != null)
            {
                throw new ArgumentOutOfRangeException("You cannot provide downscale factors without CoC values first.");
            }

            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];
            

View on GitHub (pinned to 96fad776d2)