Fix image export on macOS (hang / NSView crash) — closes #403 by calumk · Pull Request #411 · fougue/mayo

calumk · 2026-08-18T10:45:03Z

Fixes #403.

Attribution: the code and this description were written by Claude Opus 5 operating/steered as instructed on behalf of @calumk. Reviewed before submission. Please scrutinise accordingly.

Summary

Image export was unusable on macOS. mayo-conv hung forever, and the desktop app aborted with the NSView.m:13477 assertion @HuguesDelorme reproduced on Monterey. There turned out to be three independent defects stacked on top of each other — fixing any one alone still leaves export broken.

1. `Cocoa_Window` cannot be used for offscreen rendering

graphicsCreateVirtualWindow() created a Cocoa_Window. Its constructor throws when NSApp is null:

Aspect_WindowDefinitionError("Cocoa application should be instantiated before window")

NSApp is always null in mayo-conv, which builds a QCoreApplication. Caught with an lldb throw breakpoint:

Cocoa_Window::Cocoa_Window + 464
Mayo::graphicsCreateVirtualWindow
Mayo::IO::ImageWriter::createV3dView
Mayo::IO::ImageWriter::writeFile          ← on thread #4 (std::async worker)

Cocoa_Window also allocates a real on-screen NSWindow and retains its contentView. Export runs on a worker thread, and touching NSView off the main thread is illegal — this is the source of the assertion crash in the desktop app, which is why the GUI failed differently from the CLI.

Fix: use Aspect_NeutralWindow on macOS, merging with the existing Android branch. Mayo already relies on Aspect_NeutralWindow elsewhere (OcctNeutralWindow in qtopengl_utils.cpp).

2. The exception became an infinite hang

This explains the "hangs, file is not generated" symptom rather than an error message.

TaskManager::Private::execEntity() called the job unguarded. The throw escaped into the std::async future — which is stored but never waited on, so the exception was silently swallowed. Consequently signalEnded never fired → exportTaskCount never reached zero → qtApp->exit() was never called → QCoreApplication::exec() blocked forever in poll().

Fix, defence in depth:

task_manager.cpp — guard the job call so signalEnded is always emitted and isFinished always set.
io_system.cpp — wrap writer transfer/writeFile in a helper that catches Standard_Failure (reporting DynamicType()->Name() + GetMessageString()), std::exception and ....
cli_export.cpp — gsl::finally so the task counter is always decremented.

Any OCCT throw in an export path now surfaces as a proper error message instead of a hang.

3. `ToPixMap()` failed on a stale GL error

Only visible after #1 was fixed:

2D texture 128x128 IF: GL_SRGB8_ALPHA8 PF: GL_RGBA DT: GL_UNSIGNED_BYTE
can not be created with error GL_INVALID_FRAMEBUFFER_OPERATION [:color]
Warning, on screen buffer is used for image dump - content might be invalid

A drawable-less GL context has an incomplete default framebuffer, so OCCT's own glDrawBuffer(GL_BACK) in OpenGl_Window::init() raises GL_INVALID_FRAMEBUFFER_OPERATION and never clears it. OpenGl_Texture::Init() then reads that stale error while building the dump FBO and wrongly concludes texture creation failed.

Confirmed a false negative with a standalone probe: a view-less NSOpenGLContext (GL_VERSION 4.1 Metal - 90.5) created the same texture with error 0x0, got FBO status = GL_FRAMEBUFFER_COMPLETE, and read back the expected pixels. A/B test in-tree: without the error reset ToPixMap returns 0; with it, 1.

Fix: add graphicsPrepareVirtualWindowRendering(), which makes the context current and calls ResetErrors(). It must be called immediately before ToPixMap() — doing it only at view creation is too early, because Redraw() re-raises the error.

Also: ImageWriter::writeFile() now emits real errors instead of return false silently.

Testing

macOS 26.5 arm64 (M-series), Qt 6.10.2, OpenCascade 7.9.3, AppleClang 21.

mayo-conv and the desktop app both export successfully; no hang, no assertion crash
Inputs verified: STEP, IGES, BREP, OBJ, STLB, PLY, glTF
Sizes up to 3840×2160
Two concurrent --export targets in one invocation
Invalid input now produces a clean error and exit code 0 instead of hanging
Output images inspected visually — real geometry, not blank frames
Test suite: 225 passed, 0 failed

Caveats

Only tested on macOS arm64. I have no Linux or Windows machine here. The Aspect_NeutralWindow change is inside #elif defined(MAYO_OS_MAC) || defined(MAYO_OS_ANDROID) so other platforms are untouched, but the task_manager.cpp and io_system.cpp changes are cross-platform and deserve a look — they are defensive only and change no success-path behaviour.
Worth confirming on an Intel Mac; the probe was arm64.
Homebrew's OCCT is built without FreeImage, so Image_AlienPixMap::Save() writes Netpbm/PPM data whatever the extension (file reports Netpbm image data, header P6). That is an OCCT packaging matter, not a Mayo bug, but it does mean .png output is not really PNG on a stock Homebrew install.

Image export was unusable on macOS: `mayo-conv` hung forever and the desktop app aborted on an NSView assertion. Three distinct defects were involved. 1. Cocoa_Window cannot be used for offscreen rendering graphicsCreateVirtualWindow() created a Cocoa_Window, whose constructor throws Aspect_WindowDefinitionError("Cocoa application should be instantiated before window") when NSApp is null. That is always the case in mayo-conv, which builds a QCoreApplication. Cocoa_Window also allocates a real on-screen NSWindow and retains its contentView. Export tasks run on a worker thread, and touching NSView off the main thread is illegal, which produced the assertion reported in fougue#403: Assertion failed: (NSViewIsCurrentlyBuildingLayerTreeForDisplay() != currentlyBuildingLayerTree), NSView.m:13477 Use Aspect_NeutralWindow on macOS instead, merging with the existing Android branch. Mayo already relies on Aspect_NeutralWindow elsewhere (see OcctNeutralWindow in qtopengl_utils.cpp). 2. The exception turned into an infinite hang TaskManager::Private::execEntity() invoked the job unguarded, so the throw escaped into the std::async future. That future is stored but never waited on, so the exception was silently swallowed, signalEnded never fired, exportTaskCount never reached zero, and QCoreApplication::exec() blocked forever in poll(). Guard the job call so signalEnded is always emitted, wrap writer transfer/write in a Standard_Failure-aware helper in io_system.cpp, and use gsl::finally in cli_export.cpp so the task counter is always decremented. 3. ToPixMap() failed on a stale GL error A drawable-less GL context has an incomplete default framebuffer, so the glDrawBuffer(GL_BACK) call in OpenGl_Window::init() raises GL_INVALID_FRAMEBUFFER_OPERATION and never clears it. OpenGl_Texture::Init() later reads that stale error while building the dump FBO and wrongly reports: 2D texture 128x128 IF: GL_SRGB8_ALPHA8 PF: GL_RGBA DT: GL_UNSIGNED_BYTE can not be created with error GL_INVALID_FRAMEBUFFER_OPERATION This is a false negative: an isolated probe confirmed the texture and FBO are created correctly (FBO status GL_FRAMEBUFFER_COMPLETE) and read back the expected pixels. Add graphicsPrepareVirtualWindowRendering(), which makes the context current and clears pending errors. It must be called immediately before ToPixMap(); doing it only at view creation is too early because Redraw() re-raises the error. Also report real errors from ImageWriter::writeFile() instead of returning false silently. Tested on macOS 26.5 arm64, Qt 6.10.2, OpenCascade 7.9.3, for both mayo-conv and the desktop app. Export verified for STEP, IGES, BREP, OBJ, STL, PLY and glTF inputs, at sizes up to 3840x2160, including concurrent exports and invalid-input error paths. Test suite: 225 passed, 0 failed. Not tested on Linux or Windows. Written by Claude Opus 5 operating/steered as instructed on behalf of @calumk. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

HuguesDelorme · 2026-08-21T10:32:03Z

+    }
+    catch (const Standard_Failure& err) {
+        return fnError(
+            fmt::format("Exception '{}': {}", err.DynamicType()->Name(), err.GetMessageString())


Compilation fails with OpenCascade 8.0.0 (latest version) because of API change
Please do :
fmt::format("Exception '{}': {}", TKernelUtils::errorTypeName(err), TKernelUtils::errorMessage(err))

HuguesDelorme · 2026-08-21T10:43:43Z


    const bool okSave = pixmap->Save(filepathTo<TCollection_AsciiString>(filepath));
+    if (!okSave) {
+        this->messenger()->emitError(fmt::format(


This message doesn't need the surrounding fmt::format()

HuguesDelorme · 2026-09-01T16:40:19Z

Is it possible to remove "Claude" as co-author ? I dislike the idea an AI to be member of contributors in Mayo repo

HuguesDelorme · 2026-09-01T17:10:21Z

@calumk
I may take your changes in a bugfix branch, test and adapt and them merge in develop branch (mentionning your groundwork, many thanks for that). Do you agree ?

calumk · 2026-09-01T17:35:12Z

I may take your changes in a bugfix branch, test and adapt and them merge in develop branch (mentionning your groundwork, many thanks for that). Do you agree ?

Of course!

Feel free to close, pull from this, or ignore it completely etc -

As i said most of this was not really my ground work, it was just me digging through and itterating / testing with to find the big and some route causes - But it did at least get a functioning system working

I dont need to be credited in any way, the only goal for me is that mayo becomes a little more stable on mac :)

HuguesDelorme · 2026-09-01T17:39:13Z

Feel free to close, pull from this, or ignore it completely etc -

As i said most of this was not really my ground work, it was just me digging through and itterating / testing with to find the big and some route causes - But it did at least get a functioning system working

I dont need to be credited in any way, the only goal for me is that mayo becomes a little more stable on mac :)

Thanks, then I'm going to have a deeper look of your 2 PRs
Please continue to report/contribute any issue/PR for mac support!
Will let you know about my progress, thanks again

HuguesDelorme · 2026-09-07T17:01:02Z

@calumk

Can you please test my branch that incorporates changes of your PR ?
The branch to checkout is tests/io-image
To be tested :

mayo-conv : export to image
export to image from within mayo app
check the thumbnails are correctly created for files recently opened in mayo

This was referenced Aug 18, 2026

Image export not working #403

Open

mayo-conv: image export renders BRep shapes as wireframe (no meshing) #412

Open

cli: mesh BRep shapes when exporting to image — closes #412 #413

Open

HuguesDelorme reviewed Aug 21, 2026

View reviewed changes

HuguesDelorme mentioned this pull request Sep 1, 2026

Wiki: note that Homebrew OpenCascade lacks FreeImage, so macOS image export writes PPM data under any extension #414

Open

Navigation Menu

Uh oh!

Uh oh!

Fix image export on macOS (hang / NSView crash) — closes #403 - #411

Fix image export on macOS (hang / NSView crash) — closes #403#411
calumk wants to merge 1 commit into
fougue:developfrom
calumk:fix/macos-image-export

calumk commented Aug 18, 2026 •

edited

Loading

Uh oh!

HuguesDelorme Aug 21, 2026

Uh oh!

HuguesDelorme Aug 21, 2026

Uh oh!

HuguesDelorme commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 1, 2026 •

edited

Loading

Uh oh!

calumk commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

calumk commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

1. Cocoa_Window cannot be used for offscreen rendering

2. The exception became an infinite hang

3. ToPixMap() failed on a stale GL error

Testing

Caveats

Related

Uh oh!

HuguesDelorme Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

HuguesDelorme Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

HuguesDelorme commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

calumk commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 1, 2026

Uh oh!

HuguesDelorme commented Sep 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

calumk commented Aug 18, 2026 •

edited

Loading

1. `Cocoa_Window` cannot be used for offscreen rendering

3. `ToPixMap()` failed on a stale GL error

HuguesDelorme commented Sep 1, 2026 •

edited

Loading