stride3d/stride · error · ArgumentOutOfRangeException

value

Error message

value

What it means

RadiancePrefilteringGGX.SamplingsCount setter throws ArgumentOutOfRangeException when the assigned value exceeds 1024. SamplingsCount controls the number of importance-sampled GGX lookups per prefiltered mip; values above 1024 are rejected because the effect's sample loop/constant buffer is designed for at most 1024 samples.

Solutions

1. Set SamplingsCount to a value <= 1024 (e.g. 512).
2. Use a power of 2 value such as 128, 256, 512 for the quality/perf tradeoff you need.
3. Clamp the loaded value: Math.Min(userValue, 1024) before assigning.

Example fix

// before
prefilter.SamplingsCount = 2048;
// after
prefilter.SamplingsCount = Math.Min(2048, 512); // <= 1024, power of 2

if (samplings > 1024)
    throw new ArgumentOutOfRangeException(nameof(samplings), "Max SamplingsCount is 1024");
prefilter.SamplingsCount = samplings;

bool IsValidSamplingsCount(int v) => v <= 1024 && MathUtil.IsPow2(v) && v >= 1;

try { prefilter.SamplingsCount = value; }
catch (ArgumentOutOfRangeException ex) { Log.Warning("SamplingsCount > 1024, clamping to 1024"); prefilter.SamplingsCount = 1024; }

When it happens

Trigger: Assigning e.g. environmentRadiancePrefilteringGGX.SamplingsCount = 2048 before rendering.

Common situations: Trying to increase prefilter quality beyond the supported maximum; loading a persisted scene/asset that stored an out-of-range sample count; confusion between this property and other engines' unbounded sample counts.

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

• value
• The provided value should be a power of 2
• The provided value should be a power of 2
• Source texture is not a MSAA texture.
• Destination texture is a MSAA texture.

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

Appendix: source

Thrown at sources/engine/Stride.Rendering/Rendering/ComputeEffect/GGXPrefiltering/RadiancePrefilteringGGX.cs:63

        public RadiancePrefilteringGGX(RenderContext context)
            : base(context, "RadiancePrefilteringGGX")
        {
            computeShader = new ComputeEffectShader(context) { ShaderSourceName = "RadiancePrefilteringGGXEffect" };
            DoNotFilterHighestLevel = true;
            samplingsCount = 1024;
        }

        /// <summary>
        /// Gets or sets the number of sampling used during the importance sampling
        /// </summary>
        /// <remarks>Should be a power of 2 and maximum value is 1024</remarks>
        public int SamplingsCount
        {
            get { return samplingsCount; }
            set
            {
                if (value > 1024)
                    throw new ArgumentOutOfRangeException("value");

                if (!MathUtil.IsPow2(value))
                    throw new ArgumentException("The provided value should be a power of 2");

                samplingsCount = Math.Max(1, value);
            }
        }

        protected override void DrawCore(RenderDrawContext context)
        {
            var output = PrefilteredRadiance;
            if (output == null || (output.ViewDimension != TextureDimension.Texture2D && output.ViewDimension != TextureDimension.TextureCube) || output.ArraySize != 6)
                throw new NotSupportedException("Only array of 2D textures are currently supported as output");

            if (!output.IsUnorderedAccess || output.IsRenderTarget)
                throw new NotSupportedException("Only non-rendertarget unordered access textures are supported as output");

            var input = RadianceMap;

View on GitHub (pinned to 96fad776d2)