{"record":{"id":"97be3c672bfb6f51","repo":"stride3d/stride","slug":"texture-streaming-supports-only-2d-textures-and-2d-texture","errorCode":null,"errorMessage":"Texture streaming supports only 2D textures and 2D texture arrays.","messagePattern":"Texture streaming supports only 2D textures and 2D texture arrays\\.","errorType":"exception","errorClass":"ContentStreamingException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Rendering/Streaming/StreamingTexture.cs","lineNumber":184,"sourceCode":"            else\n            {\n                // Stream target quality in steps\n                //requestedResidency = currentResidency - 1;\n\n                // Stream target quality at once\n                requestedResidency = targetResidency;\n            }\n\n            return requestedResidency;\n        }\n\n        /// <inheritdoc />\n        internal override bool CanBeUpdated => textureToSync == null && base.CanBeUpdated;\n\n        internal void Init(IDatabaseFileProviderService databaseFileProviderService, [NotNull] ContentStorage storage, ref ImageDescription imageDescription)\n        {\n            if (imageDescription.Depth != 1)\n                throw new ContentStreamingException(\"Texture streaming supports only 2D textures and 2D texture arrays.\", storage);\n\n            Init(databaseFileProviderService, storage);\n            texture.FullQualitySize = new Size3(imageDescription.Width, imageDescription.Height, imageDescription.Depth);\n            description = imageDescription;\n            residentMips = 0;\n            CacheMipMaps();\n        }\n\n        /// <inheritdoc />\n        internal override void FlushSync()\n        {\n            if (textureToSync == null)\n                return;\n\n            // register the new memory usage\n            Manager.RegisterMemoryUsage(textureToSync.SizeInBytes - texture.SizeInBytes);\n\n            // Texture is loaded and created in the async task.","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Rendering/Streaming/StreamingTexture.cs#L166-L202","documentation":"StreamingTexture uploads mip data incrementally into 2D or 2D-array layouts; 3D textures (imageDescription.Depth != 1) are not supported by the streaming path. Init validates this up front and throws ContentStreamingException so unsupported 3D/volume textures never enter the streaming system with wrong assumptions (FullQualitySize, mip layout).","triggerScenarios":"Calling StreamingTexture.Init (directly or via StreamingManager.RegisterTexture) with an ImageDescription whose Depth is greater than 1 — i.e. a 3D/volume texture or a texture asset flagged as streamable that is actually 3D.","commonSituations":"Volume/3D texture assets mistakenly marked for streaming; procedural textures created with depth > 1 and then registered with the StreamingManager; using texture formats/tools that emit 3D images into a pipeline configured for streaming.","solutions":["Exclude the texture from streaming: register/load it as a regular (non-streaming) texture","If the texture is meant to be 2D, fix the source asset/import so Depth == 1 (a 2D array is still Depth==1 with a depth-slice count)","Downgrade to a 2D texture or bake the volume data into a 2D atlas before streaming"],"exampleFix":"// before\nstreamingManager.RegisterTexture(myVolumeTexture, myVolumeTexture.Description); // Depth > 1 -> throws\n// after\nif (description.Depth == 1)\n    streamingManager.RegisterTexture(myTexture, description);\nelse\n    // load as non-streaming texture\n    var texture = myVolumeTexture;","handlingStrategy":"validation","validationCode":"if (imageDescription.Depth != 1)\n    // register as non-streaming instead\n    return; // regular Texture load path","typeGuard":"bool IsStreamable(in ImageDescription d) => d.Depth == 1;","tryCatchPattern":"try\n{\n    streamingTexture.Init(provider, storage, ref description);\n}\ncatch (ContentStreamingException)\n{\n    // load as regular texture\n    texture = Content.Load<Texture>(url);\n}","preventionTips":["Check Depth before enabling streaming on any texture","Keep 3D/volume textures out of streaming pipelines","Validate imported assets' ImageDescription at import time"],"tags":["streaming","textures","unsupported"],"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"}