{"record":{"id":"0b38ed904fc90e63","repo":"stride3d/stride","slug":"alphaloadmode-alphaloadmode-not-supported-for-the-stride","errorCode":null,"errorMessage":"AlphaLoadMode.{alphaLoadMode} not supported for the Stride image format (no premultiplied-state metadata).","messagePattern":"AlphaLoadMode\\.(.+?) not supported for the Stride image format \\(no premultiplied-state metadata\\)\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Foundation/Graphics/ImageHelper.cs","lineNumber":32,"sourceCode":"    public class ImageHelper\n    {\n        internal static DataSerializer<ImageDescription> ImageDescriptionSerializer = SerializerSelector.Default.GetSerializer<ImageDescription>();\n        internal static readonly FourCC MagicCode = \"TKTX\";\n\n        public static unsafe Image LoadFromMemory(IntPtr pSource, int size, bool makeACopy, GCHandle? handle, AlphaLoadMode alphaLoadMode)\n        {\n            Debug.Assert(size >= 0);\n            var ums = new UnmanagedMemoryStream((byte*)pSource, size, capacity: size, access: FileAccess.Read);\n            var stream = new BinarySerializationReader(ums);\n\n            // Read and check magic code\n            var magicCode = stream.ReadUInt32();\n            if (magicCode != MagicCode)\n                return null;\n\n            // Stride's own format doesn't carry a premul-state flag; we can't honor conversion requests safely.\n            if (alphaLoadMode != AlphaLoadMode.Preserve)\n                throw new NotSupportedException($\"AlphaLoadMode.{alphaLoadMode} not supported for the Stride image format (no premultiplied-state metadata).\");\n\n            // Read header\n            var imageDescription = new ImageDescription();\n            ImageDescriptionSerializer.Serialize(ref imageDescription, ArchiveMode.Deserialize, stream);\n\n            if (makeACopy)\n            {\n                var buffer = MemoryUtilities.Allocate(size);\n                MemoryUtilities.CopyWithAlignmentFallback((void*)buffer, source: (void*)pSource, (uint)size);\n                pSource = buffer;\n                makeACopy = false;\n            }\n\n            var image = new Image(imageDescription, pSource, 0, handle, !makeACopy);\n\n            var totalSizeInBytes = stream.ReadInt32();\n            if (totalSizeInBytes != image.TotalSizeInBytes)\n                throw new InvalidOperationException(\"Image size is different than expected.\");","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Foundation/Graphics/ImageHelper.cs#L14-L50","documentation":"LoadFromMemory parsing a Stride-native image (.sdtex) refuses any AlphaLoadMode other than Preserve. The Stride image container has no metadata recording whether pixel data is already premultiplied, so the library cannot correctly perform premultiply/unpremultiply conversions and throws NotSupportedException instead of silently producing wrong alpha. Thrown as NotSupportedException from LoadFromMemory in ImageHelper.cs when alphaLoadMode != AlphaLoadMode.Preserve.","triggerScenarios":"Calling ImageHelper.LoadFromMemory(stream, makeACopy, alphaLoadMode) with a stream whose magic code matches the Stride image format, while passing AlphaLoadMode.Premultiply or AlphaLoadMode.Unpremultiply. Only AlphaLoadMode.Preserve is valid for this container format.","commonSituations":"Sharing one image-loading code path across file formats where non-Stride loaders (e.g. PNG via StandardImageHelper) do honor alpha load modes; refactoring code that used to load PNGs to load Stride-native images; explicitly requesting premultiplied data for rendering pipelines that require it.","solutions":["Pass AlphaLoadMode.Preserve when loading Stride-format images.","Convert the asset to a format with premultiplied-state metadata (e.g. PNG or DDS) if alpha conversion is required.","Branch on format first (read the magic code yourself) and only pass non-Preserve modes to formats that support it."],"exampleFix":"// before\nvar image = ImageHelper.LoadFromMemory(stream, makeACopy: true, alphaLoadMode: AlphaLoadMode.Premultiply);\n// after\nvar image = ImageHelper.LoadFromMemory(stream, makeACopy: true, alphaLoadMode: AlphaLoadMode.Preserve);","handlingStrategy":"validation","validationCode":"if (alphaLoadMode != AlphaLoadMode.Preserve)\n    throw new ArgumentException($\"{alphaLoadMode} requires a format with premultiplied-state metadata; use Preserve for Stride images.\");","typeGuard":null,"tryCatchPattern":"try { image = ImageHelper.LoadFromMemory(stream, makeACopy, alphaLoadMode); }\ncatch (NotSupportedException) { image = ImageHelper.LoadFromMemory(stream, makeACopy, AlphaLoadMode.Preserve); }","preventionTips":["Use AlphaLoadMode.Preserve as the default for Stride-native assets.","Centralize image loading so alpha-mode policy is decided per format in one place.","Document which asset formats support alpha conversion."],"tags":["graphics","image-loading","alpha-premultiply","not-supported"],"backgroundTag":"unsupported-operation","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}