{"record":{"id":"af1059c9e16ff786","repo":"d2phap/ImageGlass","slug":"ige-native-codec-codecid-returned-an-unsuppor","errorCode":null,"errorMessage":"IGE: Native codec '{CodecId}' returned an unsupported pixel format ({buffer.PixelFormat}).","messagePattern":"IGE: Native codec '(.+?)' returned an unsupported pixel format \\((.+?)\\)\\.","errorType":"exception","errorClass":"InvalidDataException","httpStatus":null,"severity":"error","filePath":"source/ImageGlass.Lib/Plugins/NativeCodecProxy.cs","lineNumber":807,"sourceCode":"    /// <summary>\n    /// Wraps a plugin-owned <see cref=\"IGPixelBuffer\"/> in an <see cref=\"SKImage\"/>\n    /// without copying the pixels. The returned image owns the plugin buffer:\n    /// disposing the image calls back into the plugin's <c>FreePixelBuffer</c>\n    /// via the release delegate (which the SDK contract requires to be thread-safe).\n    /// </summary>\n    internal SKImage WrapPluginBufferAsImage(in IGPixelBuffer buffer, SKColorSpace? srcColorSpace)\n    {\n        // Validate the buffer before we hand it to Skia.\n        if (buffer.Data == null || buffer.Width <= 0 || buffer.Height <= 0)\n        {\n            throw new InvalidDataException(\n                $\"IGE: Native codec '{CodecId}' returned an invalid pixel buffer.\");\n        }\n\n        var (colorType, alphaType) = MapPixelFormat((IGPixelFormat)buffer.PixelFormat);\n        if (colorType == SKColorType.Unknown)\n        {\n            throw new InvalidDataException(\n                $\"IGE: Native codec '{CodecId}' returned an unsupported pixel format ({buffer.PixelFormat}).\");\n        }\n\n        var info = new SKImageInfo(buffer.Width, buffer.Height, colorType, alphaType);\n        if (srcColorSpace is not null)\n        {\n            info = info.WithColorSpace(srcColorSpace);\n        }\n\n        // Carrier holds the plugin codec API + a copy of the buffer descriptor so\n        // SkiaSharp can hand the pointer back to the plugin on dispose.\n        var carrier = new PluginPixelBufferRelease\n        {\n            CodecApiPtr = (nint)_codecApi,\n            Buffer = buffer,\n            PluginId = _plugin.PluginId,\n            LiveToken = _plugin.LiveToken,\n        };","sourceCodeStart":789,"sourceCodeEnd":825,"githubUrl":"https://github.com/d2phap/ImageGlass/blob/4a3c4feceffc5a8bb5e56ba836509634aaae47a9/source/ImageGlass.Lib/Plugins/NativeCodecProxy.cs#L789-L825","documentation":"Thrown by NativeCodecProxy.WrapPluginBufferAsImage when MapPixelFormat returns SKColorType.Unknown for the buffer's declared IGPixelFormat. The host supports a fixed set of pixel formats (Bgra8Unorm and a few others); the plugin picked a format outside that set, so Skia cannot interpret the bytes.","triggerScenarios":"Produced at NativeCodecProxy.cs:807 when the IGPixelFormat in IGPixelBuffer.PixelFormat does not map to any known SKColorType. The plugin successfully produced pixels but in a layout the host cannot consume.","commonSituations":"Plugin author chose a format not in the host's MapPixelFormat table (e.g. a Planar YUV, a 16-bit planar HDR, or a vendor-specific format); ABI drift where PixelFormat lands at the wrong offset and reads as a garbage int; plugin built against an older SDK that used different IGPixelFormat enum values.","solutions":["Have the plugin output one of the host-supported formats — Bgra8Unorm is the canonical one (see ReadPixelsInto comment about why BGRA Unpremul is mandatory).","Update MapPixelFormat in NativeCodecProxy if a new legitimate format was added to the SDK and the host should accept it.","Verify the plugin is built against the same IGPixelFormat enum values as the host (no enum drift).","Disable the plugin and let a built-in codec decode the file in a host-native format."],"exampleFix":"// before\nvar (colorType, alphaType) = MapPixelFormat((IGPixelFormat)buffer.PixelFormat);\nif (colorType == SKColorType.Unknown)\n    throw new InvalidDataException($\"IGE: Native codec '{CodecId}' returned an unsupported pixel format ({buffer.PixelFormat}).\");\n\n// after — name the enum value so the plugin author knows which format was rejected\nvar (colorType, alphaType) = MapPixelFormat((IGPixelFormat)buffer.PixelFormat);\nif (colorType == SKColorType.Unknown)\n    throw new InvalidDataException(\n        $\"IGE: Native codec '{CodecId}' returned an unsupported pixel format \" +\n        $\"({(IGPixelFormat)buffer.PixelFormat} = {buffer.PixelFormat}). Supported: Bgra8Unorm.\");","handlingStrategy":"validation","validationCode":"// Before WrapPluginBufferAsImage, check the format maps to a known Skia color type.\nvar (ct, _) = MapPixelFormat((IGPixelFormat)buffer.PixelFormat);\nif (ct == SKColorType.Unknown)\n    throw new InvalidDataException($\"Plugin returned unsupported format {(IGPixelFormat)buffer.PixelFormat}\");","typeGuard":"static bool IsSupportedFormat(IGPixelFormat f) =>\n    MapPixelFormat(f).colorType != SKColorType.Unknown;","tryCatchPattern":"try { image = proxy.WrapPluginBufferAsImage(in buffer, colorSpace); }\ncatch (InvalidDataException ex) when (ex.Message.Contains(\"unsupported pixel format\"))\n{ _log.Warn($\"Plugin {proxy.CodecId} emitted {buffer.PixelFormat}; requesting Bgra8Unorm.\"); return BuiltInFallback(metadata); }","preventionTips":["Have plugins output Bgra8Unorm (the canonical host format) unless they have a specific reason not to.","Extend MapPixelFormat if a new legitimate format was added to the SDK.","Ensure plugin and host share the same IGPixelFormat enum values (no enum drift).","Document the supported format list in the plugin SDK so authors do not pick unsupported ones."],"tags":["plugin","codec","native","pixel-format","skiasharp"],"backgroundTag":null,"analyzedSha":"4a3c4feceffc5a8bb5e56ba836509634aaae47a9","analyzedAt":"2026-08-13T16:58:15.523Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}