04 — EngineHost (L3)¶

Sole C# host border. Project: src/Nps.EngineHost/. Every [DllImport] in the repo lives in NpsAbi.cs (DllName = "NPSEngine", NpsAbi.cs:43); the csproj header (Nps.EngineHost.csproj:62-66) documents this as an enforced rule — apps and shell never redeclare ABI.

NpsAbi¶

public static class NpsAbi (NpsAbi.cs:41), all exports CallingConvention.Cdecl. Enums: NpsResult (:49), FindingSeverity (:72), LoadMode (:75), GcodeMoveType (:78). ExpectedAbiVersion = 1 (:238) — hosts assert it at startup.

Wire ids (string constants, not enums):

• OverlayModeId (:88-95): motion-type (:90 — the overlay-panel "None" radio maps here, it is an active mode, not a no-op), thermal, warp-risk, bond-strength, cooling-eff
• FindingCategoryId (:101-108): thermal, structural, motion, hole, retraction, flow (6 wire ids)

POD mirrors (lockstep with nps_c_api.h, static_assert-frozen on the C side)¶

Export map by domain (managed decl → C entry point)¶

Apps and tests call NpsAbi.* only through this assembly — never redeclare DllImport.

SafeHandles¶

Invariant: every engine + viewport handle reaches C# through a SafeHandle; never raw IntPtr + manual Destroy for owned resources (SafeEngineHandle.cs:29-32). Viewport handles are owned by Nps.Shell ViewportController, not by EngineSession.

EngineSession public surface¶

public sealed class EngineSession : IDisposable (EngineSession.cs:67). Sole owner of its SafeEngineHandle (:73); single-threaded UI-thread session. Raw-handle access is private IntPtr DangerousHandle (:463) plus internal IntPtr RawEngineHandle (:500) — there is no public DangerousGetEngineHandle; only MeshController (same assembly) uses the internal accessor.

All members throw ObjectDisposedException after Dispose via ThrowIfInvalid/DangerousHandle (:463-473).

Result records (all readonly record struct, same file)¶

MeshController public surface¶

public sealed class MeshController (MeshController.cs:71). Read-only projection of engine mesh + palette. Holds a reference to EngineSession — does NOT own its lifetime (:79); disposing the session under a live controller is a programming error (:28-33). Snapshot copies engine pointers into stable managed arrays so the render loop never touches engine-owned memory (no pinning, no DangerousGetHandle, no unsafe, :36-40).

Private copy helpers: LoadPlate (:183), CopyFloats (:202, Marshal.Copy), CopyUInt32 (:214 — via int[] + Buffer.BlockCopy because no IntPtr→uint[] overload exists, :221-226), CopyBytes (:234).

PlateMesh (MeshController.cs:253)¶

Apps and MeshCanvasPainter iterate spans only — no mesh-geometry P/Invoke on the hot path.

Marshalling patterns (with examples)¶

1. Unmanaged-heap struct marshal instead of pinning — structs with ByValArray/ByValTStr reference fields cannot be GCHandle.Alloc(Pinned) ("Object contains references"), so the session uses Marshal.AllocHGlobal + StructureToPtr + finally { FreeHGlobal }: gen params EngineSession.cs:271-290, material profile :348-366. Contrast: strictly-blittable NpsLoadOptions MAY be pinned or passed IntPtr.Zero.
2. Engine-owned string pointers — IntPtr return + null-check + Marshal.PtrToStringAnsi, never freed by host, valid until next Load/Parse/Destroy: EngineSession.cs:139 (generated gcode), :215 (last error), :239 (model unit).
3. Byte-buffer string-out — [Out] byte[] outBuf, UIntPtr maxLen, UTF-8 NUL-terminated, truncation = cap-1 bytes + NUL (NpsAbi.cs:267-274): GetInferredMaterialType (:277), GetInferredSlicerType (:280), GetInferredPrinter (:285), GetSupportedOverlayIds (:472).
4. [Out] array fills with count probe — probe, allocate, fill, trim: findings summary EngineSession.cs:381-400.
5. out / ref structs — out NpsAnalysisFinding (NpsAbi.cs:461); ref NpsWarpGrid (:480).
6. ref UIntPtr outCount pointer queries — engine returns IntPtr + element count: mesh arrays (NpsAbi.cs:310-316), GetWarpGridRisk (:483); consumed via Marshal.Copy (MeshController.cs:210, 228, 242).
7. Fixed-size LPArray out-buffers — MVP 16 (NpsAbi.cs:416), heatmap RGB 3 (:497), orbit XY 2 (:503).
8. LPArray inputs — overlay values (:426, :434), bgcode bytes (:380).
9. LPStr strings in — paths (:252), gcode text (:377), overlay ids (:422, :464).
10. I1 bools — [MarshalAs(UnmanagedType.I1)] for simulating (:420), warp active (:424), invert (:428).
11. ByValTStr / ByValArray inline in PODs — finding category/message/ suggestion (NpsAbi.cs:164-171), reserved tails int[4] (:122, :139).
12. UIntPtr for size_t counts throughout (e.g. :366, :407).

Resource ownership¶

• EngineSession is the sole owner of its SafeEngineHandle (ownsHandle: true, EngineSession.cs:190); Dispose → DestroyEngine.
• SafeGcodeViewportHandle ownership lives in Nps.Shell ViewportController — not in EngineSession.
• MeshController holds a non-owning session reference; the app owns the session.
• Move buffer (LastMovesPointer) is engine-owned; the session only snapshots pointer + count; valid until next LoadModel/Generate. UI iterates via ReadOnlySpan/unsafe without copying.
• Mesh snapshot: MeshController copies into owned managed arrays on Reload, so render-loop spans never alias engine memory.
• Golden-fixture caveat: 4-colors+Benchy+AMS+test-v2.3mf loads as 1 plate / 16562 verts / 33097 tris / 4 palette colors through the LoadModel → Reload path above.

Mapping to C ABI¶

Forbidden¶

• No second P/Invoke surface in apps or shell.
• No domain parsing in C#.
• No Test* imports in production host code.

See also¶

• shell-and-apps.md
• c-abi.md
• user-flows.md