stride3d/stride · error · ArgumentException

Invalid Z slice index

Error message

Invalid Z slice index

What it means

GetPixelBuffer validates zIndex against Description.Depth for 3D (volume) textures. Requesting a Z slice beyond the image's depth is rejected with an ArgumentException. For 1D/2D images Depth is 1, so any zIndex above 0 throws.

Solutions

1. Guard zIndex against image.Description.Depth before the call
2. Skip z iteration (use 0) for 1D/2D images where Depth is 1
3. Recreate the image with the required Depth if the slice should exist

Example fix

// before
var buf = image.GetPixelBuffer(0, z, 0); // any z
// after
if (z < image.Description.Depth)
    var buf = image.GetPixelBuffer(0, z, 0);

if ((uint)zIndex >= image.Description.Depth) throw new ArgumentOutOfRangeException(nameof(zIndex));
var buf = image.GetPixelBuffer(0, zIndex, 0);

bool IsValidZSlice(Image image, int z) => (uint)z < image.Description.Depth;

try { var buf = image.GetPixelBuffer(0, z, 0); }
catch (ArgumentException ex) when (ex.ParamName == "zIndex") { /* skip slice */ }

When it happens

Trigger: Calling image.GetPixelBuffer(arrayIndex, zIndex, mipmap) with zIndex > image.Description.Depth — e.g. accessing z=3 on a 2D image (Depth=1) or z >= texture depth on a volume texture.

Common situations: Using the same triple-index loop for 2D and 3D textures without honoring Description.Depth; passing world-space or texel z coordinates instead of a slice index; treating a 3D texture's depth as pixel height.

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

• The offset must be either -1, 0 or 1
• MipLevels must be <=
• Width/Height/Depth must be power of 2
• Image format not supported
• This file format is not yet implemented.

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

Appendix: source

Thrown at sources/engine/Stride.Foundation/Graphics/Image.cs:260

        /// <summary>
        /// Gets the pixel buffer for the specified array/z slice and mipmap level.
        /// </summary>
        /// <param name="arrayIndex">Index into the texture array. Must be set to 0 for 3D images.</param>
        /// <param name="zIndex">Z index for 3D image. Must be set to 0 for all 1D/2D images.</param>
        /// <param name="mipmap">The mipmap.</param>
        /// <returns>A <see cref="Graphics.PixelBuffer"/>.</returns>
        /// <exception cref="ArgumentException">If arrayIndex, zIndex or mipmap are out of range.</exception>
        public PixelBuffer GetPixelBuffer(int arrayIndex, int zIndex, int mipmap)
        {
            // Check for parameters, as it is easy to mess up things...
            if (mipmap > Description.MipLevels)
                throw new ArgumentException("Invalid mipmap level", nameof(mipmap));

            if (arrayIndex > Description.ArraySize)
                throw new ArgumentException("Invalid array slice index", nameof(arrayIndex));

            if (zIndex > Description.Depth)
                throw new ArgumentException("Invalid Z slice index", nameof(zIndex));

            return GetPixelBufferUnsafe(arrayIndex, zIndex, mipmap);
        }

        /// <summary>
        ///   Registers a loader / saver for a specified Image file type.
        /// </summary>
        /// <param name="type">
        ///   The file type. Use an integer and explicit casting to <see cref="ImageFileType"/> to register other file formats.
        /// </param>
        /// <param name="loader">
        ///   A delegate that will be invoked to load an Image of the specified <paramref name="type"/>.
        ///   Specify <see langword="null"/> to register no loading delegate for this type.
        /// </param>
        /// <param name="saver">
        ///   A delegate that will be invoked to save an Image of the specified <paramref name="type"/>.
        ///   Specify <see langword="null"/> to register no saving delegate for this type.
        /// </param>

View on GitHub (pinned to 96fad776d2)