{"record":{"id":"04914b7335f1535a","repo":"AvaloniaUI/Avalonia","slug":"unable-to-export-iosurfaceref","errorCode":null,"errorMessage":"Unable to export IOSurfaceRef","messagePattern":"Unable to export IOSurfaceRef","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"samples/GpuInterop/VulkanDemo/VulkanImage.cs","lineNumber":267,"sourceCode":"        }\n\n        public IntPtr ExportIOSurface()\n        {\n            if (!Api.TryGetDeviceExtension<ExtMetalObjects>(_instance, _device, out var ext))\n                throw new InvalidOperationException();\n            var surfaceExport = new ExportMetalIOSurfaceInfoEXT\n            {\n                SType = StructureType.ExportMetalIOSurfaceInfoExt,\n                Image = InternalHandle\n            };\n            var export = new ExportMetalObjectsInfoEXT()\n            {\n                SType = StructureType.ExportMetalObjectsInfoExt,\n                PNext = &surfaceExport\n            };\n            ext.ExportMetalObjects(_device, ref export);\n            if (surfaceExport.IoSurface == IntPtr.Zero)\n                throw new Exception(\"Unable to export IOSurfaceRef\");\n            return surfaceExport.IoSurface;\n        }\n        \n        public IPlatformHandle Export()\n        {\n            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))\n            {\n                if (_d3dTexture2D.Handle != null)\n                {\n                    return new PlatformHandle(\n                        CreateDxgiSharedHandle(),\n                        KnownPlatformGraphicsExternalImageHandleTypes.D3D11TextureNtHandle);\n                }\n\n                return new PlatformHandle(ExportOpaqueNtHandle(),\n                    KnownPlatformGraphicsExternalImageHandleTypes.VulkanOpaqueNtHandle);\n            }\n            else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/samples/GpuInterop/VulkanDemo/VulkanImage.cs#L249-L285","documentation":"On macOS the sample uses VK_EXT_metal_objects (vkExportMetalObjects) to obtain a real IOSurface backing a Vulkan image. After the call it checks surfaceExport.IoSurface; if it is IntPtr.Zero the export failed and it throws a generic Exception. A zero handle means Metal/IOSurface export did not resolve for that image.","triggerScenarios":"Calling ExportIOSurface() on a Vulkan image that was not created with the Metal objects export chain, or on a device/instance without VK_EXT_metal_objects. Also when the image's external-memory Metal-IOSurface create-info was omitted.","commonSituations":"Running on macOS with an outdated MoltenVK that lacks VK_EXT_metal_objects; creating the VkImage without VK_IMAGE_USAGE_* / external-memory Metal flags; export attempted before vkBindImageMemory with the Metal export pNext; missing IOSurface framework entitlements.","solutions":["Enable VK_EXT_metal_objects on the Vulkan instance/device and update MoltenVK to a version that supports it.","Create the VkImage with the ExportMetalObjectUsageInfoEXT / ExternalMemoryImageCreateInfo (Metal IOSurface) pNext chain and the right usage flags.","Call vkBindImageMemory with dedicated allocation before exporting.","If IOSurface export is unsupported on this GPU, use the GrContext/Skia dump path instead (see error 24)."],"exampleFix":"// before\next.ExportMetalObjects(_device, ref export);\nif (surfaceExport.IoSurface == IntPtr.Zero)\n    throw new Exception(\"Unable to export IOSurfaceRef\");\n\n// after (verify the extension is present first)\nif (!enabledExtensions.Contains(KnownExt.VkExtMetalObjects))\n    throw new NotSupportedException(\"VK_EXT_metal_objects is required to export an IOSurface.\");\next.ExportMetalObjects(_device, ref export);\nif (surfaceExport.IoSurface == IntPtr.Zero)\n    throw new InvalidOperationException(\"vkExportMetalObjects returned a null IOSurface; the image was not created with a Metal export chain.\");","handlingStrategy":"validation","validationCode":"// verify the extension before exporting\nif (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX) || !HasExtension(VkExt.MetalObjects))\n    return; // cannot export IOSurface here","typeGuard":"static bool CanExportIOSurface(VkDevice dev, ISet<string> ext) =>\n    RuntimeInformation.IsOSPlatform(OSPlatform.OSX) && ext.Contains(VK_EXT_METAL_OBJECTS);","tryCatchPattern":"try { var surf = ExportIOSurface(); }\ncatch (Exception ex) when (ex.Message.Contains(\"IOSurfaceRef\"))\n{ _logger.LogWarning(\"IOSurface export unavailable; skipping Metal interop.\"); }","preventionTips":["Enable VK_EXT_metal_objects on macOS.","Build the VkImage with the Metal IOSurface export pNext chain.","Update MoltenVK to a version supporting VK_EXT_metal_objects."],"tags":["vulkan","macos","metal","iosurface","external-memory","sample"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}