ZeroSpace/.junie/plans/fix-mapbackground-platformimage-constructor-error.md

sessionId

sessionId
session-260928-184444-1lki

Requirements

Overview & Goals

Fix the build error in ZeroSpace.MapEditor/Services/MapBackground.cs where invoking new PlatformImage(buffer) fails with compilation error CS7036: There is no argument given that corresponds to the required parameter 'bitmap' of 'PlatformImage.PlatformImage(ICanvasResourceCreator, CanvasBitmap)'.

Scope

• In Scope:
  • Fix the image instantiation logic in ZeroSpace.MapEditor/Services/MapBackground.cs to use Microsoft.Maui.Graphics.Platform.PlatformImage.FromStream(buffer).
  • Ensure compatibility with .NET MAUI Windows (net10.0-windows10.0.19041.0) and MacCatalyst (net10.0-maccatalyst).
  • Verify project build and clean diagnostic status.
• Out of Scope:
  • Modifying the galaxy map raw asset or canvas drawing logic in MapEditorPage.xaml.cs and MapEditorDrawable.cs.
  • Introducing external third-party image decoding dependencies.

Functional Requirements

• MapBackground.LoadAsync() must asynchronously open galaxymap.png from app package assets, copy the stream into memory, and return a valid Microsoft.Maui.Graphics.IImage instance on supported platforms.
• If the asset cannot be found or is loaded on an unsupported platform, MapBackground.LoadAsync() must catch the exception and return null without crashing the application.
• MapEditorPage must continue to display the galaxy map background when enabled.

Non-Functional Requirements

• Maintain zero build errors and zero warnings across all supported target frameworks.
• Preserve memory stream behavior ensuring stream data remains accessible for lazy platform decoders.

Technical Design

Current Implementation

In ZeroSpace.MapEditor/Services/MapBackground.cs:

#if WINDOWS
    return new Microsoft.Maui.Graphics.Platform.PlatformImage(buffer);
#elif MACCATALYST
    return new Microsoft.Maui.Graphics.Platform.PlatformImage(buffer);
#else
    return null;
#endif

On Windows (Microsoft.Maui.Graphics.Win2D), PlatformImage has no single-parameter constructor accepting a Stream. Its constructor expects (ICanvasResourceCreator, CanvasBitmap) or (byte[], ImageFormat).

Root Cause

Directly calling the PlatformImage constructor with a MemoryStream is invalid in Microsoft.Maui.Graphics for Win2D. The supported API to construct an IImage from a Stream across all MAUI platforms is the static factory method PlatformImage.FromStream(Stream, ImageFormat).

Key Decisions

• Decision: Use PlatformImage.FromStream(buffer) instead of constructor invocation.
  • Rationale: PlatformImage.FromStream(Stream, ImageFormat) is the standard Microsoft.Maui.Graphics API designed for stream-based image creation on both Windows and MacCatalyst platforms.

Proposed Changes

• In ZeroSpace.MapEditor/Services/MapBackground.cs:
  • Update lines 25–31 to invoke Microsoft.Maui.Graphics.Platform.PlatformImage.FromStream(buffer) under #if WINDOWS || MACCATALYST.
  • Maintain the existing try-catch safety wrapper that returns null if loading fails.

File Structure

• ZeroSpace.MapEditor/Services/MapBackground.cs (Modified: update image factory call)
• ZeroSpace.MapEditor/Views/MapEditorPage.xaml.cs (Referenced: consumes MapBackground.LoadAsync())

Testing

Validation Approach

Verify that the compilation error CS7036 is resolved and ZeroSpace.MapEditor builds successfully.

Key Scenarios

• Compilation Check:
  • Verify ZeroSpace.MapEditor/Services/MapBackground.cs with Rider code analysis to confirm zero compiler errors.
  • Build ZeroSpace.MapEditor.csproj target framework net10.0-windows10.0.19041.0.
• Image Loading & Fallback Check:
  • Ensure MapBackground.LoadAsync() returns an IImage instance when galaxymap.png is available.
  • Ensure exceptions during loading (e.g. missing asset) are handled cleanly and return null.

Delivery Steps

✓ Step 1: Refactor image stream loading to use PlatformImage.FromStream in MapBackground

MapBackground.cs compiles without CS7036 errors across target platforms by using the static factory method PlatformImage.FromStream.

• Replace new Microsoft.Maui.Graphics.Platform.PlatformImage(buffer) with Microsoft.Maui.Graphics.Platform.PlatformImage.FromStream(buffer) in ZeroSpace.MapEditor/Services/MapBackground.cs.
• Consolidate platform conditional directives #if WINDOWS || MACCATALYST (or use platform-agnostic graphics loading) while preserving graceful null fallback in the catch block and unsupported target platforms.
• Ensure using directives for Microsoft.Maui.Graphics.Platform are properly configured.

✓ Step 2: Verify compilation and image rendering integration

ZeroSpace.MapEditor builds cleanly without diagnostics or runtime issues when loading raw background assets.

• Run code analysis/diagnostics on ZeroSpace.MapEditor/Services/MapBackground.cs to confirm zero compilation errors and warnings.
• Build the ZeroSpace.MapEditor project to ensure proper integration with Microsoft.Maui.Controls and Microsoft.Maui.Graphics.
• Validate that MapEditorPage.xaml.cs successfully receives the IImage instance from MapBackground.LoadAsync() and invalidates the map canvas for rendering.