{"record":{"id":"3a97765c259c4b0d","repo":"stride3d/stride","slug":"iosurface-import-requires-vk-ext-metal-objects","errorCode":null,"errorMessage":"IOSurface import requires VK_EXT_metal_objects.","messagePattern":"IOSurface import requires VK_EXT_metal_objects\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Vulkan/Texture.Apple.Vulkan.cs","lineNumber":60,"sourceCode":"        {\n            if (ioSurfaceRef != IntPtr.Zero)\n            {\n                CFRelease(ioSurfaceRef);\n                ioSurfaceRef = IntPtr.Zero;\n            }\n        }\n\n        /// <summary>\n        /// Imports a CoreVideo IOSurface as a sampleable BGRA8_sRGB <see cref=\"Texture\"/> via VK_EXT_metal_objects.\n        /// Retains the IOSurface for the lifetime of the returned Texture; the caller is free to dispose its\n        /// CVPixelBuffer once this call returns.\n        /// </summary>\n        public static unsafe Texture NewFromIOSurface(GraphicsDevice device, IntPtr ioSurface, int width, int height)\n        {\n            if (device == null) throw new ArgumentNullException(nameof(device));\n            if (ioSurface == IntPtr.Zero) throw new ArgumentNullException(nameof(ioSurface));\n            if (!device.HasMetalObjectsSupport)\n                throw new InvalidOperationException(\"IOSurface import requires VK_EXT_metal_objects.\");\n\n            CFRetain(ioSurface);\n\n            var ioSurfaceInfo = new VkImportMetalIOSurfaceInfoEXT\n            {\n                sType = VkStructureType.ImportMetalIOSurfaceInfoEXT,\n                ioSurface = ioSurface,\n            };\n\n            var imageCreateInfo = new VkImageCreateInfo\n            {\n                sType = VkStructureType.ImageCreateInfo,\n                pNext = &ioSurfaceInfo,\n                imageType = VkImageType.Image2D,\n                format = VkFormat.B8G8R8A8Srgb,\n                extent = new VkExtent3D(width, height, 1),\n                mipLevels = 1,\n                arrayLayers = 1,","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/Texture.Apple.Vulkan.cs#L42-L78","documentation":"Texture.NewFromIOSurface imports an Apple IOSurface as a Vulkan texture on macOS/iOS, which requires the VK_EXT_metal_objects extension (device.HasMetalObjectsSupport). If the Vulkan implementation (e.g. MoltenVK) does not report support, Stride throws InvalidOperationException instead of attempting the import.","triggerScenarios":"Calling Texture.NewFromIOSurface(device, ioSurface, w, h) on a GraphicsDevice whose physical device lacks VK_EXT_metal_objects, or where the extension was not enabled at device creation; using a Vulkan ICD other than MoltenVK with no Metal interop support.","commonSituations":"macOS builds with a non-MoltenVK Vulkan loader/ICD; old MoltenVK versions before VK_EXT_metal_objects support; creating the Vulkan device without requesting VK_EXT_metal_objects; attempting IOSurface sharing on iOS where support configuration differs.","solutions":["Check device.HasMetalObjectsSupport before calling and fall back to uploading texture data normally when it is false.","Upgrade MoltenVK to a version supporting VK_EXT_metal_objects and rebuild the Vulkan device enabling the extension in the device extension list.","Ensure the GraphicsDevice creation requests VK_EXT_metal_objects (and dependency VK_KHR_portability_subset where needed) rather than using a default device config.","Verify you are actually on the Vulkan/MoltenVK backend and not another backend misconfigured to use the Vulkan IOSurface path."],"exampleFix":"// before\nvar texture = Texture.NewFromIOSurface(device, surfaceHandle, width, height);\n\n// after\nif (device.HasMetalObjectsSupport)\n    texture = Texture.NewFromIOSurface(device, surfaceHandle, width, height);\nelse\n    texture = UploadSurfaceData(device, surfaceHandle, width, height);","handlingStrategy":"validation","validationCode":"if (device == null || ioSurface == IntPtr.Zero) throw new ArgumentException(\"Invalid device or IOSurface.\");\nif (!device.HasMetalObjectsSupport)\n    throw new NotSupportedException(\"VK_EXT_metal_objects unavailable; IOSurface import not supported.\");","typeGuard":"bool CanImportIOSurface(GraphicsDevice device) => device != null && device.HasMetalObjectsSupport;","tryCatchPattern":"try\n{\n    texture = Texture.NewFromIOSurface(device, ioSurface, width, height);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"VK_EXT_metal_objects\"))\n{\n    texture = UploadSurfaceData(device, ioSurface, width, height);\n}","preventionTips":["Gate IOSurface imports behind device.HasMetalObjectsSupport.","Use a recent MoltenVK and enable VK_EXT_metal_objects at device creation.","Verify at app startup which Vulkan ICD is active on macOS.","Keep a CPU-side texture upload fallback for machines without metal_objects support."],"tags":["vulkan","macos","iosurface","moltenvk","extension-missing"],"backgroundTag":"feature-not-enabled","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"}