stride3d/stride · error · ArgumentOutOfRangeException

Quality should be between

Error message

Quality should be between {minQuality} and {maxQuality} for dither level {Dither}

What it means

FXAAEffect.UpdateParameters throws ArgumentOutOfRangeException when the Quality property is outside the valid range for the current Dither level. Each dithering level only supports a specific FXAA_QUALITY__PRESET range, computed via GetQualityRange(Dither), and the shader preset index is derived as (int)Dither + Quality, so out-of-range values would produce an invalid shader permutation.

Solutions

1. Query GetQualityRange(Dither) and clamp Quality into [minQuality, maxQuality] before rendering.
2. Adjust Dither to a level that supports the desired Quality value.
3. Call UpdateParameters only after both Dither and Quality are set to consistent values.

Example fix

// before
fxaa.Dither = DitherType.Low;
fxaa.Quality = 20; // out of range for Low
// after
var (minQ, maxQ) = FXAAEffect.GetQualityRange(DitherType.Low);
fxaa.Dither = DitherType.Low;
fxaa.Quality = Math.Clamp(20, minQ, maxQ);

var (minQ, maxQ) = FXAAEffect.GetQualityRange(dither);
fxaa.Quality = Math.Clamp(desiredQuality, minQ, maxQ);
fxaa.Dither = dither;

try { fxaa.Dither = dither; fxaa.Quality = q; }
catch (ArgumentOutOfRangeException ex) { Log.Error(ex, "FXAA quality out of range for dither level"); }

When it happens

Trigger: Setting Quality below minQuality or above maxQuality for the current Dither value before rendering; changing Dither to a level whose quality range excludes the already-set Quality.

Common situations: Hard-coding a quality value that was valid for one dither level but not another; UI sliders that don't clamp to GetQualityRange; copying FXAA settings between projects with different dither levels.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• A negative number of mip maps is not allowed.
• antialiasShaderName
• ArgumentOutOfRangeException
• ArgumentOutOfRangeException
• ArgumentOutOfRangeException

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

Appendix: source

Thrown at sources/engine/Stride.Rendering/Rendering/Images/AntiAliasing/FXAAEffect.cs:94

            {
                case DitherType.Medium:
                    return (0, 5);
                case DitherType.Low:
                    return (0, 9);
                case DitherType.None:
                    return (9, 9);
                default:
                    throw new ArgumentOutOfRangeException(nameof(Dither));
            }
        }

        protected override void UpdateParameters()
        {
            base.UpdateParameters();
            Parameters.Set(GreenAsLumaKey, InputLuminanceInAlpha ? 0 : 1);
            var (minQuality, maxQuality) = GetQualityRange(Dither);
            if (Quality < minQuality || Quality > maxQuality)
                throw new ArgumentOutOfRangeException(nameof(Quality), $"Quality should be between {minQuality} and {maxQuality} for dither level {Dither}");
            Parameters.Set(QualityKey, (int)Dither + Quality);
        }

        /// <summary>
        /// The dithering level used by FXAA.
        /// </summary>
        public enum DitherType
        {
            [Display("Medium (Fastest)")]
            Medium = 10,

            [Display("Low (Normal)")]
            Low = 20,

            [Display("None (Slowest)")]
            None = 30,
        }
    }

View on GitHub (pinned to 96fad776d2)