stride3d/stride · error · ArgumentException

Invalid z slice index

Error message

Invalid z slice index

What it means

Thrown by Image.GetPixelBuffer when the texture is 3D and arrayOrZSliceIndex exceeds Description.Depth. For Texture3D textures the second parameter indexes a Z slice and must be within the texture's depth at that mip level.

Solutions

  1. Loop with zSlice < image.Description.Depth for 3D textures
  2. Branch on Description.Dimension to pick the right range (Depth for 3D, ArraySize otherwise)
  3. Recreate the image with a larger Depth if more slices are genuinely needed

Example fix

// before
for (int z = 0; z <= image.Description.Depth; z++)
    var pb = image.GetPixelBuffer(z, mip);
// after
for (int z = 0; z < image.Description.Depth; z++)
    var pb = image.GetPixelBuffer(z, mip);
Defensive patterns

Strategy: validation

Validate before calling

if (image.Description.Dimension == TextureDimension.Texture3D && (zSlice < 0 || zSlice >= image.Description.Depth))
    throw new ArgumentOutOfRangeException(nameof(zSlice), zSlice, $"Z slice must be in [0,{image.Description.Depth})");

Type guard

bool IsValidZSlice(Image image, int slice) =>
    image.Description.Dimension == TextureDimension.Texture3D
        ? slice >= 0 && slice < image.Description.Depth
        : slice >= 0 && slice < image.Description.ArraySize;

Try / catch

try
{
    var pb = image.GetPixelBuffer(zSlice, mip);
}
catch (ArgumentException ex) when (ex.ParamName == "arrayOrZSliceIndex")
{
    log.Warn($"Z slice {zSlice} out of range for 3D texture (Depth={image.Description.Depth})");
    return null;
}

Prevention

When it happens

Trigger: image.GetPixelBuffer(zSlice, mip) on a Texture3D image where zSlice >= Description.Depth, e.g. iterating slices with '<=' or using an ArraySize-style loop on a 3D texture.

Common situations: Treating a 3D (volume) texture like a 2D texture array and looping over ArraySize instead of Depth; using slice counts from a source volume asset larger than the allocated texture.

Related errors

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

Appendix: source

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

        }

        /// <summary>
        /// Gets the pixel buffer for the specified array/z slice and mipmap level.
        /// </summary>
        /// <param name="arrayOrZSliceIndex">For 3D image, the parameter is the Z slice, otherwise it is an index into the texture array.</param>
        /// <param name="mipmap">The mipmap.</param>
        /// <returns>A <see cref="Graphics.PixelBuffer"/>.</returns>
        /// <exception cref="ArgumentException">If arrayOrZSliceIndex or mipmap are out of range.</exception>
        public PixelBuffer GetPixelBuffer(int arrayOrZSliceIndex, 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 (Description.Dimension == TextureDimension.Texture3D)
            {
                if (arrayOrZSliceIndex > Description.Depth)
                    throw new ArgumentException("Invalid z slice index", nameof(arrayOrZSliceIndex));

                // For 3D textures
                return GetPixelBufferUnsafe(0, arrayOrZSliceIndex, mipmap);
            }

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

            // For 1D, 2D textures
            return GetPixelBufferUnsafe(arrayOrZSliceIndex, 0, mipmap);
        }

        /// <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>

View on GitHub (pinned to 96fad776d2)