stride3d/stride · error · NotSupportedException

VkFormat ' ' has no equivalent PixelFormat

Error message

VkFormat '{inputFormat}' has no equivalent PixelFormat

What it means

ConvertPixelFormat maps a Vulkan VkFormat back to Stride's PixelFormat enum. When a VkFormat has no entry in the mapping switch, it throws NotSupportedException naming the format. This happens for Vulkan formats Stride does not model (e.g. vendor-specific or packed formats returned by swapchain/surface queries).

Solutions

1. Map the unknown VkFormat manually to the closest supported PixelFormat before calling Stride APIs
2. Restrict surface/device format selection to formats Stride supports (extend the switch if you own the fork)
3. Upgrade Stride — newer versions add more format mappings

Example fix

// before
var pixelFormat = VulkanConvertExtensions.ConvertPixelFormat(nativeFormat);
// after
if (nativeFormat != VkFormat.B8G8R8A8Unorm && nativeFormat != VkFormat.R8G8B8A8Unorm)
    nativeFormat = VkFormat.B8G8R8A8Unorm; // fall back to a supported format
var pixelFormat = VulkanConvertExtensions.ConvertPixelFormat(nativeFormat);

// pre-check: only convert known-supported swapchain formats
VkFormat[] supported = { VkFormat.B8G8R8A8Unorm, VkFormat.R8G8B8A8Unorm };
if (!supported.Contains(nativeFormat)) nativeFormat = VkFormat.B8G8R8A8Unorm;

try { pixelFormat = VulkanConvertExtensions.ConvertPixelFormat(nativeFormat); }
catch (NotSupportedException) { pixelFormat = PixelFormat.B8G8R8A8_UNorm; /* fallback */ }

When it happens

Trigger: Calling VulkanConvertExtensions.ConvertPixelFormat(VkFormat) with a format not covered by the mapping table — commonly formats obtained from device/swapchain enumeration rather than ones Stride created.

Common situations: Querying Vulkan surface formats and feeding the result into Stride APIs; using a device whose preferred swapchain format has no PixelFormat equivalent; a newer Vulkan SDK adding formats unknown to the Stride version in use.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported texture format:
• argumentsBuffer
• Custom strides is not supported with packed PixelFormats
• ' ' is already an sRGB pixel format
• ' ' is not a sRGB format

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Vulkan/VulkanConvertExtensions.cs:275

            VkFormat.R16G16B16A16Sint => PixelFormat.R16G16B16A16_SInt,
            VkFormat.R32Uint => PixelFormat.R32_UInt,
            VkFormat.R32Sint => PixelFormat.R32_SInt,
            VkFormat.R32Sfloat => PixelFormat.R32_Float,
            VkFormat.E5B9G9R9UfloatPack32 => PixelFormat.R9G9B9E5_Sharedexp,
            VkFormat.R32G32Sfloat => PixelFormat.R32G32_Float,
            VkFormat.R32G32Uint => PixelFormat.R32G32_UInt,
            VkFormat.R32G32Sint => PixelFormat.R32G32_SInt,
            VkFormat.R32G32B32Sfloat => PixelFormat.R32G32B32_Float,
            VkFormat.R32G32B32Sint => PixelFormat.R32G32B32_SInt,
            VkFormat.R32G32B32Uint => PixelFormat.R32G32B32_UInt,
            VkFormat.R32G32B32A32Sfloat => PixelFormat.R32G32B32A32_Float,
            VkFormat.R32G32B32A32Sint => PixelFormat.R32G32B32A32_SInt,
            VkFormat.R32G32B32A32Uint => PixelFormat.R32G32B32A32_UInt,
            VkFormat.D16Unorm => PixelFormat.D16_UNorm,
            VkFormat.D24UnormS8Uint => PixelFormat.D24_UNorm_S8_UInt,
            VkFormat.D32Sfloat => PixelFormat.D32_Float,
            VkFormat.D32SfloatS8Uint => PixelFormat.D32_Float_S8X24_UInt,
            _ => throw new NotSupportedException($"VkFormat '{inputFormat}' has no equivalent PixelFormat"),
        };

        public static VkFormat ConvertPixelFormat(PixelFormat inputFormat)
        {
            ConvertPixelFormat(inputFormat, out var format, out _, out _);
            return format;
        }

        public static void ConvertPixelFormat(PixelFormat inputFormat, out VkFormat format, out int pixelSize, out bool compressed)
        {
            if (!TryConvertPixelFormat(inputFormat, out format, out pixelSize, out compressed))
                throw new InvalidOperationException("Unsupported texture format: " + inputFormat);
        }

        /// <summary>
        /// Converts a <see cref="PixelFormat"/> to its Vulkan equivalent.
        /// </summary>
        /// <returns><c>true</c> if the format has a Vulkan equivalent; otherwise <c>false</c> and <paramref name="format"/> is <see cref="VkFormat.Undefined"/>.</returns>

View on GitHub (pinned to 96fad776d2)