stride3d/stride · error · ArgumentOutOfRangeException

The region's depth [ ] cannot be greater than the…

Error message

The region's depth [{regionToCheck.Depth}] cannot be greater than the mip-level's depth [{depth}]

What it means

Thrown when a ResourceRegion's Depth exceeds the mip-level depth. For 3D textures (or arrays treated as depth) the region must fit within the mip-level's depth extent. The check guards the GPU sub-resource copy from out-of-bounds access.

Solutions

Clamp region depth to max(1, mipDepth >> mipLevel) for the target mip.
Verify you are using arrayIndex (2D arrays) rather than region Depth to select slices.
Pass the whole sub-resource (null region) when updating all slices.

Example fix

// before
var region = new ResourceRegion(0, 0, 0, w, h, volumeDepth); // base-level depth
texture.SetData(cmd, data, 0, mipLevel: 3, region);
// after
int mipDepth = Math.Max(1, volumeDepth >> 3);
var region = new ResourceRegion(0, 0, 0, w, h, mipDepth);
texture.SetData(cmd, data, 0, mipLevel: 3, region);

Defensive patterns

Strategy: validation

Validate before calling

int mipDepth = Math.Max(1, texture.Depth >> mipLevel);
if (region != null && region.Depth > mipDepth)
    throw new InvalidOperationException($"Region depth {region.Depth} exceeds mip {mipLevel} depth {mipDepth}");

Try / catch

try { texture.SetData(cmd, data, arrayIndex, mipLevel, region); }
catch (ArgumentOutOfRangeException e) when (e.ParamName == "region") { log.Error("Region depth too large for mip", e); }

Prevention

For 2D array textures use arrayIndex, not region Depth, to select slices.
Clamp Depth to the mip-level depth for 3D textures.
Test 3D uploads on the smallest mip first.

When it happens

Trigger: Calling a Texture data method with a ResourceRegion whose Depth is larger than the volume texture's mip-level depth, e.g. region depth of 16 on a 3D texture whose mip is only 4 slices deep.

Common situations: Uploading sub-volumes of 3D textures with depth taken from the base level rather than the mip level; array-slice confusion where arraySize is treated as depth.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Texture.cs:1469

            if (region.HasValue && Usage != GraphicsResourceUsage.Default)
                throw new ArgumentException($"A region can only be specified for Textures with {nameof(GraphicsResourceUsage)}.{nameof(GraphicsResourceUsage.Default)}", nameof(region));

            // Get a description for the specified mip-level
            ref readonly var mipmap = ref GetMipMapDescription(mipLevel);

            int width = mipmap.Width;
            int height = mipmap.Height;
            int depth = mipmap.Depth;

            // If we are using a region, then check that parameters are fine
            if (region is ResourceRegion regionToCheck)
            {
                if (regionToCheck.Width > width)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's width [{regionToCheck.Width}] cannot be greater than the mip-level's width [{width}]");
                if (regionToCheck.Height > height)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's height [{regionToCheck.Height}] cannot be greater than the mip-level's height [{height}]");
                if (regionToCheck.Depth > depth)
                    throw new ArgumentOutOfRangeException(nameof(region), $"The region's depth [{regionToCheck.Depth}] cannot be greater than the mip-level's depth [{depth}]");

                width = regionToCheck.Width;
                height = regionToCheck.Height;
                depth = regionToCheck.Depth;
            }

            var sizePerElement = Format.SizeInBytes;

            // Compute actual pitch
            Image.ComputePitch(Format, width, height, out var rowStride, out var textureDepthStride, out width, out height);

            // Size Of actual texture data
            int sizeOfTextureData = textureDepthStride * depth;

            int fromDataSizeInBytes = fromData.Length * sizeof(TData);

            // Check largestSize validity of data to copy from
            if (fromDataSizeInBytes < sizeOfTextureData)

View on GitHub (pinned to 96fad776d2)