AvaloniaUI/Avalonia · error · Exception

Unable to export IOSurfaceRef

Error message

Unable to export IOSurfaceRef

What it means

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.

Source

Thrown at samples/GpuInterop/VulkanDemo/VulkanImage.cs:267

        }

        public IntPtr ExportIOSurface()
        {
            if (!Api.TryGetDeviceExtension<ExtMetalObjects>(_instance, _device, out var ext))
                throw new InvalidOperationException();
            var surfaceExport = new ExportMetalIOSurfaceInfoEXT
            {
                SType = StructureType.ExportMetalIOSurfaceInfoExt,
                Image = InternalHandle
            };
            var export = new ExportMetalObjectsInfoEXT()
            {
                SType = StructureType.ExportMetalObjectsInfoExt,
                PNext = &surfaceExport
            };
            ext.ExportMetalObjects(_device, ref export);
            if (surfaceExport.IoSurface == IntPtr.Zero)
                throw new Exception("Unable to export IOSurfaceRef");
            return surfaceExport.IoSurface;
        }
        
        public IPlatformHandle Export()
        {
            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            {
                if (_d3dTexture2D.Handle != null)
                {
                    return new PlatformHandle(
                        CreateDxgiSharedHandle(),
                        KnownPlatformGraphicsExternalImageHandleTypes.D3D11TextureNtHandle);
                }

                return new PlatformHandle(ExportOpaqueNtHandle(),
                    KnownPlatformGraphicsExternalImageHandleTypes.VulkanOpaqueNtHandle);
            }
            else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))

View on GitHub (pinned to 11c5427268)

Solutions

  1. Enable VK_EXT_metal_objects on the Vulkan instance/device and update MoltenVK to a version that supports it.
  2. Create the VkImage with the ExportMetalObjectUsageInfoEXT / ExternalMemoryImageCreateInfo (Metal IOSurface) pNext chain and the right usage flags.
  3. Call vkBindImageMemory with dedicated allocation before exporting.
  4. If IOSurface export is unsupported on this GPU, use the GrContext/Skia dump path instead (see error 24).

Example fix

// before
ext.ExportMetalObjects(_device, ref export);
if (surfaceExport.IoSurface == IntPtr.Zero)
    throw new Exception("Unable to export IOSurfaceRef");

// after (verify the extension is present first)
if (!enabledExtensions.Contains(KnownExt.VkExtMetalObjects))
    throw new NotSupportedException("VK_EXT_metal_objects is required to export an IOSurface.");
ext.ExportMetalObjects(_device, ref export);
if (surfaceExport.IoSurface == IntPtr.Zero)
    throw new InvalidOperationException("vkExportMetalObjects returned a null IOSurface; the image was not created with a Metal export chain.");
Defensive patterns

Strategy: validation

Validate before calling

// verify the extension before exporting
if (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX) || !HasExtension(VkExt.MetalObjects))
    return; // cannot export IOSurface here

Type guard

static bool CanExportIOSurface(VkDevice dev, ISet<string> ext) =>
    RuntimeInformation.IsOSPlatform(OSPlatform.OSX) && ext.Contains(VK_EXT_METAL_OBJECTS);

Try / catch

try { var surf = ExportIOSurface(); }
catch (Exception ex) when (ex.Message.Contains("IOSurfaceRef"))
{ _logger.LogWarning("IOSurface export unavailable; skipping Metal interop."); }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/04914b7335f1535a. Report an issue: GitHub.