AvaloniaUI/Avalonia · error · Exception

Unable to export IOSurfaceRef

Error message

Unable to export IOSurfaceRef

What it means

On macOS the VulkanTimelineSemaphore exports a Metal shared event via VK_EXT_metal_objects and checks eventExport.MtlSharedEvent; if IntPtr.Zero it throws. Note the message says 'IOSurfaceRef' — that is a copy-paste bug (this path exports an MTLSharedEvent, not an IOSurface). A zero event means the Metal-objects export failed for the semaphore.

Source

Thrown at samples/GpuInterop/VulkanDemo/VulkanTimelineSemaphore.cs:62

    
    public unsafe IntPtr ExportSharedEvent()
    {
        if (!_resources.Api.TryGetDeviceExtension<ExtMetalObjects>(_resources.Instance, _resources.Device, out var ext))
            throw new InvalidOperationException();
        var eventExport = new ExportMetalSharedEventInfoEXT()
        {
            SType = StructureType.ExportMetalSharedEventInfoExt,
            Semaphore = Handle,
        };
        var export = new ExportMetalObjectsInfoEXT()
        {
            SType = StructureType.ExportMetalObjectsInfoExt,
            PNext = &eventExport
        };
        ext.ExportMetalObjects(_resources.Device, ref export);
        if (eventExport.MtlSharedEvent == IntPtr.Zero)
            throw new Exception("Unable to export IOSurfaceRef");
        return eventExport.MtlSharedEvent;
    }
    public IPlatformHandle Export()
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
            return new PlatformHandle(ExportSharedEvent(),
                KnownPlatformGraphicsExternalSemaphoreHandleTypes.MetalSharedEvent);
        throw new PlatformNotSupportedException();
    }
}

View on GitHub (pinned to 11c5427268)

Solutions

1. Enable VK_EXT_metal_objects and update MoltenVK to a version supporting shared-event export.
2. Create the timeline semaphore with VkExportMetalObjectCreateInfoInfoEXT (shared-event) in the pNext chain.
3. Also fix the misleading message to say 'MTLSharedEvent' instead of 'IOSurfaceRef'.
4. If export is unsupported on this macOS/GPU, fall back to CPU-side timeline emulation.

Example fix

// before
if (eventExport.MtlSharedEvent == IntPtr.Zero)
    throw new Exception("Unable to export IOSurfaceRef");

// after (correct message + extension check)
if (eventExport.MtlSharedEvent == IntPtr.Zero)
    throw new InvalidOperationException("Unable to export MTLSharedEvent; the semaphore was not created with a Metal shared-event export chain.");

// verify the Metal-objects extension is enabled before exporting
if (!OperatingSystem.IsOSPlatform(OSPlatform.OSX) || !HasExtension(VkExt.MetalObjects))
    return null;

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

try { var h = semaphore.Export(); }
catch (Exception ex) when (ex.Message.Contains("IOSurfaceRef")) // misleading message — actually MTLSharedEvent
{ _logger.LogWarning("Metal shared-event export unavailable."); }

When it happens

Trigger: Calling Export() on macOS for a timeline semaphore whose VkSemaphore was not created with the Metal shared-event export chain (ExportMetalObjectUsageInfoEXT + VkExportMetalSharedEventInfoEXT), or running without VK_EXT_metal_objects.

Common situations: Old MoltenVK without semaphore export; semaphore created without VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTL_SYNC_BIT_MVT; device/instance missing VK_EXT_metal_objects.

Related errors

• Unable to export IOSurfaceRef
• Need skia to dump textures, sorry
• Device with the corresponding LUID not found
• Not supported format
• Vulkan D3DDevice wasn't created

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