stride3d/stride · error · InvalidOperationException

Unsupported DXGI Format

Error message

Unsupported DXGI Format

What it means

Stride's Image.Initialize rejects an ImageDescription whose PixelFormat is not a valid DXGI format or is a video (block-compressed video) format. Images in Stride must use CPU-mappable pixel formats; video formats and invalid/undefined formats cannot be used to build CPU-side image buffers. The check happens first, before any allocation, so the description never reaches the buffer setup code.

Solutions

1. Set description.Format to a valid non-video PixelFormat such as PixelFormat.R8G8B8A8_UNorm or B8G8R8A8_UNorm.
2. If the format came from a serialized asset, re-import/save the asset with the current Stride version.
3. Verify with description.Format.IsValid && !description.Format.IsVideoFormat before constructing the image.
4. If you need a video texture, use the video playback API instead of Image.

Example fix

// before
var desc = new ImageDescription { Format = PixelFormat.None, Width = 256, Height = 256, Dimension = TextureDimension.Texture2D };
var img = Image.New2D(desc);
// after
var desc = new ImageDescription { Format = PixelFormat.R8G8B8A8_UNorm, Width = 256, Height = 256, Dimension = TextureDimension.Texture2D };
var img = Image.New2D(desc);

if (desc.Format == PixelFormat.None || !desc.Format.IsValid || desc.Format.IsVideoFormat)
    throw new ArgumentException($"Format {desc.Format} cannot back a CPU Image; use a non-video DXGI format.");

static bool IsUsableImageFormat(PixelFormat f) => f != PixelFormat.None && f.IsValid && !f.IsVideoFormat;

try { var img = Image.New2D(desc); }
catch (InvalidOperationException ex) when (ex.Message == "Unsupported DXGI Format")
{
    logger.LogError(ex, "Image format {Format} is invalid or video-only", desc.Format);
    desc.Format = PixelFormat.R8G8B8A8_UNorm;
    img = Image.New2D(desc);
}

When it happens

Trigger: Calling Image.New2D/New3D or constructing an Image with a description whose Format is PixelFormat.None, an undefined value, or a video format (e.g. video-encoded formats flagged IsVideoFormat). Also happens when deserializing a texture asset whose stored format enum is out of range for the current engine version.

Common situations: Passing PixelFormat.None as a default/uninitialized format; loading an asset saved with a format removed or re-flagged as video-only in a newer Stride version; hand-building ImageDescription structs copied from GPU texture descriptions that use video formats.

Related errors

• Custom strides is not supported with packed PixelFormats
• Cannot specify custom stride with mipmaps
• Invalid Width/Height/Depth/ArraySize for Image 1D
• Invalid Width/Height/Depth/ArraySize for Image 2D
• TextureCube must have an arraysize = 6

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

Appendix: source

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

            }
            throw new NotSupportedException("This file format is not yet implemented.");
        }

        static Image()
        {
            Register(ImageFileType.Stride, ImageHelper.LoadFromMemory, ImageHelper.SaveFromMemory);
            Register(ImageFileType.Dds, DDSHelper.LoadFromDDSMemory, DDSHelper.SaveToDDSStream);
            Register(ImageFileType.Gif, StandardImageHelper.LoadFromMemory, StandardImageHelper.SaveGifFromMemory);
            Register(ImageFileType.Tiff, StandardImageHelper.LoadFromMemory, StandardImageHelper.SaveTiffFromMemory);
            Register(ImageFileType.Bmp, StandardImageHelper.LoadFromMemory, StandardImageHelper.SaveBmpFromMemory);
            Register(ImageFileType.Jpg, StandardImageHelper.LoadFromMemory, StandardImageHelper.SaveJpgFromMemory);
            Register(ImageFileType.Png, StandardImageHelper.LoadFromMemory, StandardImageHelper.SavePngFromMemory);
        }

        internal unsafe void Initialize(ImageDescription description, IntPtr dataPointer, int offset, GCHandle? handle, bool bufferIsDisposable, PitchFlags pitchFlags = PitchFlags.None, int rowStride = 0)
        {
            if (!description.Format.IsValid || description.Format.IsVideoFormat)
                throw new InvalidOperationException("Unsupported DXGI Format");

            if (rowStride > 0 && description.MipLevels != 1)
                throw new InvalidOperationException("Cannot specify custom stride with mipmaps");

            this.handle = handle;

            switch (description.Dimension)
            {
                case TextureDimension.Texture1D:
                    if (description.Width <= 0 || description.Height != 1 || description.Depth != 1 || description.ArraySize == 0)
                        throw new InvalidOperationException("Invalid Width/Height/Depth/ArraySize for Image 1D");

                    // Check that miplevels are fine
                    description.MipLevels = CalculateMipLevels(description.Width, 1, description.MipLevels);
                    break;

                case TextureDimension.Texture2D:
                case TextureDimension.TextureCube:

View on GitHub (pinned to 96fad776d2)