RenderSurfaceHost.cs

using System.Drawing;
using Gondwana.Drawing;
using Gondwana.Drawing.Direct;
using Gondwana.Effects;
using Gondwana.Extensibility;
using Gondwana.Rendering.Backbuffers;
using Gondwana.Rendering.Views;
using Gondwana.Scenes;
using Gondwana.SkiaSharp;
using Gondwana.Timers;
using Microsoft.Extensions.Logging;
using SkiaSharp;
 
namespace Gondwana.Rendering;

public sealed class RenderSurfaceHost<TBackbuffer> : RenderSurfaceHostBase
    where TBackbuffer : BackbufferBase
{
    private TBackbuffer _backbuffer;
    private bool _resolutionEstablished;
    private int _logicalWidth, _logicalHeight;
    private int _presentationInvalidated = 1;
    private float _deferredRenderScale = float.NaN;
    private Scene _scene = Scene.Empty;
    private RecordingBackbuffer? _recordingBackbuffer;
    private long _snapshotSequence;
    private GpuRenderFrameDiagnostics? _recordingDiagnostics;
 
    private readonly RenderSurfaceAdapterBase _renderSurfaceAdapter;
    private readonly ViewManager _viewManager;

    public event EventHandler<RenderSurfaceHostBindEventArgs>? BindToScene;

    public event Action? RenderBackbufferBegin;

    public event Action? RenderBackbufferEnd;

    public event Action? RenderBackbufferNoOp;

    public event Action<GpuRenderFrameDiagnostics>? GpuRenderFrameDiagnosticsCalculated;

    public event Action<SKCanvas>? RenderBackbufferPostScene;
 
    private RenderSurfaceHost() : base() => _viewManager = new ViewManager(this);

    public RenderSurfaceHost(RenderSurfaceAdapterBase renderSurfaceAdapter) : this()
    {
        _renderSurfaceAdapter = renderSurfaceAdapter ?? throw new ArgumentNullException(nameof(renderSurfaceAdapter));
 
        // Host layout changes presentation; only the initial valid layout establishes resolution.
        RenderSurfaceAdapter.Resized += OnRenderSurfaceAdapterResized;
 
        var w = RenderSurfaceAdapter.Width;
        var h = RenderSurfaceAdapter.Height;
 
        if (w <= 0 || h <= 0)
            throw new InvalidOperationException("RenderSurfaceAdapter has non-positive dimensions.");
 
        _resolutionEstablished = RenderSurfaceAdapter.InitialSizeAvailable;
        var scale = Engine.Instance.Configuration.RenderScale;
        _logicalWidth = _resolutionEstablished ? PresentationTransform.ScaleDimension(w, scale) : 1;
        _logicalHeight = _resolutionEstablished ? PresentationTransform.ScaleDimension(h, scale) : 1;
        _backbuffer = CreateBackbuffer(_logicalWidth, _logicalHeight);
        Telemetry = Diagnostics.RenderTelemetry.Register(_backbuffer is GpuBackbuffer);
        RenderSurfaceAdapter.SetBackbufferSize(_logicalWidth, _logicalHeight);
        Backbuffer.BeginFrame();
 
        Backbuffer.SizeChanged += OnBackbufferSizeChanged;
    }
 
    private static TBackbuffer CreateBackbuffer(int width, int height)
    {
        var typeName = typeof(TBackbuffer).FullName;
        Console.WriteLine($"CreateBackbuffer called for type: {typeName}, dimensions: {width}x{height}");
 
        // Use explicit type checking instead of reflection to avoid trimming issues in browser/WASM
        if (typeof(TBackbuffer) == typeof(Backbuffers.BitmapBackbuffer))
        {
            Engine.Logger.LogInformation("Using explicit BitmapBackbuffer constructor for type {TypeName}", typeName);
            return (TBackbuffer)(object)new Backbuffers.BitmapBackbuffer(width, height);
        }
 
        if (typeof(TBackbuffer) == typeof(Backbuffers.GpuBackbuffer))
        {
            Engine.Logger.LogInformation("Using explicit GpuBackbuffer constructor for type {TypeName}", typeName);
            return (TBackbuffer)(object)new Backbuffers.GpuBackbuffer(width, height);
        }
 
        // Fallback to Activator for any other backbuffer types
        Engine.Logger.LogInformation("Falling back to Activator.CreateInstance for type {TypeName}", typeName);
        return (TBackbuffer)Activator.CreateInstance(typeof(TBackbuffer), width, height)!;
    }

    public override BackbufferBase Backbuffer => _backbuffer;

    public override Scene Scene => _scene;

    public override RenderSurfaceAdapterBase RenderSurfaceAdapter => _renderSurfaceAdapter;

    public override ViewManager ViewManager => _viewManager;

    public bool RedrawDirtyRectangleOnly { get; set; } = true;

    public void Bind(Scene newScene, bool limitCameraToWorldBoundPx = true)
    {
        ArgumentNullException.ThrowIfNull(newScene, "Cannot bind to null Scene.");
 
        if (ReferenceEquals(newScene, _scene))
            return;
 
        // Claim the new scene before releasing the old one. If another host owns it,
        // Bind fails without disturbing this host's current scene.
        newScene.BindRenderSurfaceHost(this);
 
        var oldScene = _scene;
 
        try
        {
            // Unregister from and release the old scene.
            if (!ReferenceEquals(oldScene, Scene.Empty))
            {
                oldScene.SceneDisposing -= OnSourceDisposing;
                oldScene.UnbindRenderSurfaceHost(this);
            }
 
            _scene = newScene;
            ViewManager.BindToScene(_scene, limitCameraToWorldBoundPx);
 
            _scene.SceneDisposing += OnSourceDisposing;
            _scene.FullRefreshNeeded = true;
        }
        catch
        {
            // Release the failed new binding and restore the previous scene.
            newScene.UnbindRenderSurfaceHost(this);
            _scene = oldScene;
 
            if (!ReferenceEquals(oldScene, Scene.Empty))
            {
                oldScene.BindRenderSurfaceHost(this);
                oldScene.SceneDisposing += OnSourceDisposing;
            }
 
            throw;
        }
 
        BindToScene?.Invoke(this, new RenderSurfaceHostBindEventArgs(oldScene, _scene));
    }

    internal override void RenderToBackbuffer(long tick)
    {
        Backbuffer.BeginFrame();
        RenderBackbufferBegin?.Invoke();
 
        // For GL-thread-rendered backbuffers (GpuBackbuffer), the RefreshQueue mechanism is
        // unreliable: AddWorldRect and ClearRefreshQueue both post to the engine thread, so
        // enqueued rects are not present when CollectDirtyScreenArea runs, and posted clears
        // can silently discard dirty rects that were added after the last GL frame.
        // Instead, always re-render the entire surface each GL paint callback.
        if (Backbuffer.IsGlThreadRendered)
            RenderToBackbufferGpuFull(tick);
        else
            RenderToBackbufferBitmap(tick);
 
        RenderBackbufferEnd?.Invoke();
    }

    internal override void ProduceRenderFrameSnapshot(long tick)
    {
        if (!UsesRenderFrameSnapshots || _disposed) return;
        var slot = FrameMailbox.TryBeginBuild();
        if (slot is null) return;
        var recorder = _recordingBackbuffer ??= new RecordingBackbuffer();
        bool transferred = false;
        long telemetryGeneration = Telemetry?.BeginSample() ?? 0;
        long started = GpuRenderFrameDiagnosticsCalculated is null && telemetryGeneration == 0 ? 0 : HighResTimer.GetCurrentTick();
        _recordingDiagnostics = null;
        try
        {
            recorder.Start(Backbuffer);
            RenderBackbufferBegin?.Invoke();
            RenderToBackbufferGpuFull(tick, recorder);
            RenderBackbufferEnd?.Invoke();
            var frame = new RenderFrameSnapshot(recorder.Complete(), ++_snapshotSequence,
                HighResTimer.GetCurrentTick(), recorder.Width, recorder.Height);
            transferred = true;
            FrameMailbox.Publish(slot, frame);
            if (telemetryGeneration != 0)
            {
                Telemetry!.Record(telemetryGeneration, "build.cpu.ms", HighResTimer.GetDuration(started, HighResTimer.GetCurrentTick()) * 1000d);
                Telemetry.Record(telemetryGeneration, "atlas.batches", recorder.AtlasBatchCount);
                Telemetry.Record(telemetryGeneration, "atlas.tiles", recorder.AtlasBatchedTileCount);
            }
            if (_recordingDiagnostics is { } diagnostics)
                GpuRenderFrameDiagnosticsCalculated?.Invoke(diagnostics with
                {
                    TotalRenderMilliseconds =
                        HighResTimer.GetDuration(started, HighResTimer.GetCurrentTick()) * 1000d,
                    AtlasBatchCount = recorder.AtlasBatchCount,
                    AtlasBatchedTileCount = recorder.AtlasBatchedTileCount
                });
        }
        catch
        {
            recorder.Cancel();
            if (!transferred) FrameMailbox.AbortBuild(slot);
            throw;
        }
    }

    private void RenderToBackbufferGpuFull(long tick, BackbufferBase? destination = null)
    {
        var target = destination ?? Backbuffer;
        long telemetryGeneration = Telemetry?.BeginSample() ?? 0;
        bool legacyDiagnostics = GpuRenderFrameDiagnosticsCalculated is not null;
        bool collectDiagnostics = legacyDiagnostics || telemetryGeneration != 0;
        long diagnosticsStartTick = collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
        long queryAndSortTicks = 0;
        long queryTicks = 0;
        long sortTicks = 0;
        long drawTicks = 0;
        long overlayTicks = 0;
        int drawableCount = 0;
        int tileCount = 0;
        List<GpuLayerRenderDiagnostics>? layerDiagnostics = legacyDiagnostics
            ? new List<GpuLayerRenderDiagnostics>(Scene.VisibleSceneLayers.Count)
            : null;
 
        // When there are no views at all, clear the whole surface and bail.
        // If there ARE views but no scene layers, we fall through so view-mode
        // DirectDrawings (e.g. a splash screen overlay) are still rendered.
        if (ViewManager.Views.Count == 0)
        {
            target.ClearRect(new Rectangle(0, 0, target.Width, target.Height));
            Scene.FullRefreshNeeded = false;
 
            if (telemetryGeneration != 0 && destination is not RecordingBackbuffer)
            {
                long diagnosticsEndTick = HighResTimer.GetCurrentTick();
                Telemetry!.Record(
                    telemetryGeneration,
                    "build.cpu.ms",
                    HighResTimer.GetDuration(diagnosticsStartTick, diagnosticsEndTick) * 1000d);
            }
 
            return;
        }
 
        // A single clear lets translucent, wiped, or translated views reveal the
        // views beneath them. Each view paints its own background as part of its
        // presentation group below.
        target.ClearRect(new Rectangle(0, 0, target.Width, target.Height));
 
        foreach (var view in ViewManager.Views)
        {
            RenderContext.Push(view, tick);
 
            try
            {
                // 1) View overlays are drawn unconditionally by this full-frame path.
                // They must not enqueue dirty regions that GL rendering never consumes.
                var overlays = DirectDrawingManager.Instance.GetDrawingsForView(view);
 
                var vp = view.GetRenderViewportTargetRectPx();
 
                // 2) Clip to this view's viewport, excluding areas covered by higher Z-order views.
                target.Canvas.Save();
                target.Canvas.ResetMatrix();
                target.Canvas.ClipRect(vp.ToSKRect(), SKClipOperation.Intersect, antialias: false);
 
                foreach (var blocker in ViewManager.GetViewsAbove(view))
                {
                    if (!blocker.BlocksViewsBelow)
                        continue;
 
                    var overlap = Rectangle.Intersect(vp, blocker.GetRenderViewportTargetRectPx());
                    if (!overlap.IsEmpty)
                        target.Canvas.ClipRect(overlap.ToSKRect(), SKClipOperation.Difference, antialias: false);
                }
 
                int viewPresentation = BeginPresentation(
                    view.GetPresentationBoundsPx(),
                    view.EffectOpacity,
                    view.EffectReveal,
                    view.EffectRevealDirection, target);
 
                if (viewPresentation > 0)
                {
                    // The view background belongs inside the group so it fades,
                    // wipes, and slides with the rest of the view.
                    target.ClearRect(view.GetPresentationBoundsPx().ToPixelAlignedRect());
 
                    // 4) Render every visible layer for the full viewport extent (layers are drawn
                    //    back-to-front by ascending Z-order, which VisibleSceneLayers already provides).
                    var sceneLayers = Scene.VisibleSceneLayers;
 
                    for (int i = 0; i < sceneLayers.Count; i++)
                    {
                        var layer = sceneLayers[i];
 
                        int layerPresentation = BeginPresentation(
                            GetLayerPresentationBounds(view, layer),
                            layer.EffectOpacity,
                            layer.EffectReveal,
                            layer.EffectRevealDirection, target);
 
                        if (layerPresentation == 0)
                            continue;
 
                        // Compute the world-space rect visible through this viewport for this layer,
                        // expanded by one tile in each direction to cover boundary rounding.
                        var layerWorldRectF = view.ScreenRectToWorldRect(layer, vp);
                        layerWorldRectF.Inflate(layer.TileWidth, layer.TileHeight);
                        var layerWorldRect = layerWorldRectF.ToPixelAlignedRect();
 
                        long queryStartTick =
                            collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                        long layerSortTicks = 0;
                        int layerDrawableCount;
                        int layerTileCount;
 
                        var recording = target as RecordingBackbuffer;
                        RecordingBackbuffer.FixedGridRenderPlan fixedGridPlan = default;
                        bool streamed = recording is not null &&
                            recording.TryPrepareFixedGridLayer(
                                layer,
                                layerWorldRect,
                                out fixedGridPlan);
 
                        long queryEndTick;
                        long drawStartTick;
                        long drawEndTick;
 
                        if (streamed)
                        {
                            queryEndTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
 
                            drawStartTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                            layerTileCount = recording!.DrawFixedGridLayer(
                                view,
                                fixedGridPlan,
                                vp);
                            layerDrawableCount = layerTileCount;
                            drawEndTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                        }
                        else
                        {
                            List<IDrawable> drawables;
                            if (collectDiagnostics)
                            {
                                drawables = layer.GetDrawablesInWorldRectWithDiagnostics(
                                    layerWorldRect,
                                    out layerSortTicks);
                            }
                            else
                            {
                                drawables = layer.GetDrawablesInWorldRect(layerWorldRect);
                            }
 
                            queryEndTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
 
                            layerDrawableCount = drawables.Count;
                            layerTileCount = 0;
                            if (collectDiagnostics)
                            {
                                for (int d = 0; d < drawables.Count; d++)
                                {
                                    IDrawable drawable = drawables[d] is WrappedDrawable wrapped
                                        ? wrapped.Owner
                                        : drawables[d];
 
                                    if (drawable is Tile)
                                        layerTileCount++;
                                }
                            }
 
                            drawStartTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                            target.DrawDrawables(view, drawables, vp);
                            drawEndTick =
                                collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                        }
 
                        if (collectDiagnostics)
                        {
                            long layerQueryAndSortTicks = queryEndTick - queryStartTick;
                            long layerQueryTicks = Math.Max(
                                0L,
                                layerQueryAndSortTicks - layerSortTicks);
                            long layerDrawTicks = drawEndTick - drawStartTick;
                            queryAndSortTicks += layerQueryAndSortTicks;
                            queryTicks += layerQueryTicks;
                            sortTicks += layerSortTicks;
                            drawTicks += layerDrawTicks;
                            drawableCount += layerDrawableCount;
                            tileCount += layerTileCount;
 
                            if (telemetryGeneration != 0 && i < Diagnostics.RenderTelemetry.Layers.Length)
                            {
                                var keys = Diagnostics.RenderTelemetry.Layers[i];
                                Telemetry!.Record(telemetryGeneration, keys[0], HighResTimer.GetDuration(0, layerQueryTicks) * 1000d);
                                Telemetry.Record(telemetryGeneration, keys[1], HighResTimer.GetDuration(0, layerDrawTicks) * 1000d);
                                Telemetry.Record(telemetryGeneration, keys[2], layerDrawableCount);
                                Telemetry.Record(telemetryGeneration, keys[3], layerTileCount);
                                Telemetry.Record(telemetryGeneration, keys[4], layer.TransformedTiles.Count);
                                Telemetry.Record(telemetryGeneration, keys[5], layer.TileWidth);
                                Telemetry.Record(telemetryGeneration, keys[6], layer.TileHeight);
                                Telemetry.Record(telemetryGeneration, keys[7], layer.ZOrder);
                            }
 
                            layerDiagnostics?.Add(new GpuLayerRenderDiagnostics(
                                i,
                                layer.ID,
                                layer.ZOrder,
                                layerDrawableCount,
                                layerTileCount,
                                layer.TransformedTiles.Count,
                                layer.TileWidth,
                                layer.TileHeight,
                                HighResTimer.GetDuration(0, layerQueryAndSortTicks) * 1000d,
                                HighResTimer.GetDuration(0, layerDrawTicks) * 1000d));
                        }
 
                        EndPresentation(layerPresentation, target);
                    }
 
                    // 5) Render view-based DirectDrawings on top.
                    long overlayStartTick = collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
                    for (int i = 0; i < overlays.Count; i++)
                        overlays[i].Draw(target, overlays[i].GetDrawLocationScreen(view));
                    long overlayEndTick = collectDiagnostics ? HighResTimer.GetCurrentTick() : 0;
 
                    if (collectDiagnostics)
                        overlayTicks += overlayEndTick - overlayStartTick;
 
                    EndPresentation(viewPresentation, target);
                }
 
                target.Canvas.Restore();
            }
            finally
            {
                RenderContext.Pop();
            }
        }
 
        Scene.FullRefreshNeeded = false;
 
        // Desktop snapshots record these hooks on the Engine thread; WebGL invokes
        // them synchronously against its GPU canvas.
        InvokePostSceneCanvasHooks(target);
 
        if (collectDiagnostics)
        {
            long diagnosticsEndTick = HighResTimer.GetCurrentTick();
            if (telemetryGeneration != 0)
            {
                if (destination is not RecordingBackbuffer)
                    Telemetry!.Record(telemetryGeneration, "build.cpu.ms", HighResTimer.GetDuration(diagnosticsStartTick, diagnosticsEndTick) * 1000d);
                Telemetry!.Record(telemetryGeneration, "query.cpu.ms", HighResTimer.GetDuration(0, queryTicks) * 1000d);
                Telemetry.Record(telemetryGeneration, "sort.cpu.ms", HighResTimer.GetDuration(0, sortTicks) * 1000d);
                Telemetry.Record(telemetryGeneration, "record.cpu.ms", HighResTimer.GetDuration(0, drawTicks) * 1000d);
                Telemetry.Record(telemetryGeneration, "overlay.cpu.ms", HighResTimer.GetDuration(0, overlayTicks) * 1000d);
                Telemetry.Record(telemetryGeneration, "visible.drawables", drawableCount);
                Telemetry.Record(telemetryGeneration, "visible.tiles", tileCount);
                Telemetry.Record(telemetryGeneration, "layers.omitted", Math.Max(0, Scene.VisibleSceneLayers.Count - Diagnostics.RenderTelemetry.Layers.Length));
                if (Scene.VisibleSceneLayers.Count > Diagnostics.RenderTelemetry.Layers.Length)
                    Telemetry.MarkTruncated(telemetryGeneration);
            }
            if (!legacyDiagnostics) return;
            var diagnostics = new GpuRenderFrameDiagnostics(
                HighResTimer.GetDuration(diagnosticsStartTick, diagnosticsEndTick) * 1000d,
                HighResTimer.GetDuration(0, queryAndSortTicks) * 1000d,
                HighResTimer.GetDuration(0, drawTicks) * 1000d,
                HighResTimer.GetDuration(0, overlayTicks) * 1000d,
                drawableCount,
                tileCount,
                layerDiagnostics!)
            {
                QueryMilliseconds = HighResTimer.GetDuration(0, queryTicks) * 1000d,
                SortMilliseconds = HighResTimer.GetDuration(0, sortTicks) * 1000d
            };
            if (destination is RecordingBackbuffer) _recordingDiagnostics = diagnostics;
            else GpuRenderFrameDiagnosticsCalculated?.Invoke(diagnostics);
        }
    }

    private void RenderToBackbufferBitmap(long tick)
    {
        if (ViewManager.Views.Count == 0)
        {
            Backbuffer.ClearRect(new Rectangle(0, 0, Backbuffer.Width, Backbuffer.Height));
            Scene.FullRefreshNeeded = false;
            return;
        }
 
        bool fullViewComposition = ViewManager.Views.Any(view => view.HasPresentationEffect)
            || Scene.VisibleSceneLayers.Any(layer => layer.WrapHorizontally || layer.WrapVertically);
 
        // 0) If there are no visible SceneLayers, just clear and publish the full frame.
        if (Scene.CountOfVisibleLayers == 0)
        {
            Backbuffer.ClearRect(new Rectangle(0, 0, Backbuffer.Width, Backbuffer.Height));
            Scene.FullRefreshNeeded = false;
        }
        else
        {
            // 1) Handle full scene refresh once (camera moved, zoom changed, etc.): clear and mark all layers as dirty.
            //    This already clears the whole backbuffer and enqueues a full rect per layer.
            if (Scene.FullRefreshNeeded || (fullViewComposition && Scene.IsDirty))
            {
                // this will mark the Scene.IsDirty flag as true
                EnqueueFullSceneRefresh();
            }
            else
            {
                // scene is not dirty, this frame is done...
                if (!Scene.IsDirty)
                {
                    RenderBackbufferNoOp?.Invoke();
                    return;
                }
            }
        }
 
        if (fullViewComposition)
            Backbuffer.ClearRect(new Rectangle(0, 0, Backbuffer.Width, Backbuffer.Height));
 
        // 2) Render all views to Backbuffer. Draw layers back -> front (ascending Z).
        foreach (var view in ViewManager.Views)
        {
            RenderContext.Push(view, tick);
 
            try
            {
                // 2.1) Force-refresh all DirectDrawings that overlay this view
                var overlays = DirectDrawingManager.Instance.GetDrawingsForView(view);
                foreach (var overlay in overlays)
                {
                    overlay.ForceRefresh();
                }
 
                // 2.2) identify dirty SCREEN areas across all layers for this view
                var dirtyScreenRects = CollectDirtyScreenArea(view);
 
                // 2.3) Clip to this view's viewport
                var vp = view.GetRenderViewportTargetRectPx();
 
                // clip inclusive to current viewport
                Backbuffer.Canvas.Save();
                Backbuffer.Canvas.ResetMatrix();
                Backbuffer.Canvas.ClipRect(vp.ToSKRect(), SKClipOperation.Intersect, antialias: false);
 
                // clip exclusive to higher Z-order views
                foreach (var blocker in ViewManager.GetViewsAbove(view))
                {
                    if (!blocker.BlocksViewsBelow)
                        continue;
 
                    var overlap = Rectangle.Intersect(vp, blocker.GetRenderViewportTargetRectPx());
                    if (!overlap.IsEmpty)
                        Backbuffer.Canvas.ClipRect(overlap.ToSKRect(), SKClipOperation.Difference, antialias: false);
                }
 
                int viewPresentation = BeginPresentation(
                    view.GetPresentationBoundsPx(),
                    view.EffectOpacity,
                    view.EffectReveal,
                    view.EffectRevealDirection);
 
                if (viewPresentation > 0)
                {
                    if (fullViewComposition)
                    {
                        Backbuffer.ClearRect(view.GetPresentationBoundsPx().ToPixelAlignedRect());
                    }
                    else
                    {
                        // 2.4) Pre-clear dirty areas on backbuffer to Backbuffer.ClearColor
                        PreclearScreenAreas(view, dirtyScreenRects);
                    }
 
                    // 2.5) Render each visible layer's dirty regions for this view
                    //      this will draw SceneLayerTiles, Sprites, and SceneLayer-based DirectDrawings
                    var sceneLayers = Scene.VisibleSceneLayers;
 
                    for (int i = 0; i < sceneLayers.Count; i++)
                    {
                        var layer = sceneLayers[i];
                        int layerPresentation = BeginPresentation(
                            GetLayerPresentationBounds(view, layer),
                            layer.EffectOpacity,
                            layer.EffectReveal,
                            layer.EffectRevealDirection);
 
                        if (layerPresentation == 0)
                            continue;
 
                        RenderLayerDirtyRegions(view, layer);
                        EndPresentation(layerPresentation);
                    }
 
                    // 2.6) draw all View-based DirectDrawings for this view
                    for (int i = 0; i < overlays.Count; i++)
                        overlays[i].Draw(Backbuffer, overlays[i].GetDrawLocationScreen(view));
 
                    EndPresentation(viewPresentation);
                }
 
                // 2.7) Restore from viewport clip
                Backbuffer.Canvas.Restore();
            }
            finally
            {
                RenderContext.Pop();
            }
        }
 
        // 3) Clear layer queues now that we've consumed them (avoids re-drawing same tiles next frame)
        for (int i = 0; i < Scene.CountOfVisibleLayers; i++)
            Scene.VisibleSceneLayers[i].RefreshQueue.ClearRefreshQueue();
 
        Scene.FullRefreshNeeded = false;
 
        // Notify subscribers that all scene content has been drawn and the canvas is ready for
        // post-scene effects.  Fires before RenderBackbufferEnd so subscribers still have a
        // chance to draw into the canvas before it is presented to the adapter.
        InvokePostSceneCanvasHooks();
    }
 
    #region DrawRefreshQueueToBackbuffer helpers
 
    private void EnqueueFullSceneRefresh()
    {
        foreach (var view in ViewManager.Views)
        {
            var viewport = view.Viewport;
            var screenRect = viewport.TargetRectPx;
 
            for (int i = 0; i < Scene.CountOfVisibleLayers; i++)
            {
                var layer = Scene.VisibleSceneLayers[i];
 
                // 1) Compute layer-specific visible world rect
                var layerWorldRect = view.ScreenRectToWorldRect(layer, screenRect);
 
                // 2) Expand world rect by **one full tile** in all directions.
                //    This compensates for fractional-layer motion (parallax),
                //    camera motion, and tile boundaries.
                int expandX = layer.TileWidth;
                int expandY = layer.TileHeight;
 
                layerWorldRect.Inflate(expandX, expandY);
 
                // 3) Round to ints and enqueue
                var worldRectInt = layerWorldRect.ToPixelAlignedRect();
 
                layer.RefreshQueue.AddWorldRect(worldRectInt);
            }
        }
    }
 
    private List<Rectangle> CollectDirtyScreenArea(View view)
    {
        var dirty = new List<Rectangle>(64);
        var viewportRect = view.GetRenderViewportTargetRectPx();
 
        foreach (var sceneLayer in Scene.VisibleSceneLayers)
        {
            var refreshQueue = sceneLayer.RefreshQueue;
            if (!refreshQueue.IsDirty)
                continue;
 
            foreach (var worldRect in refreshQueue.SnapshotWorldRects())
            {
                var screenRectF = view.WorldRectToScreenRect(sceneLayer, worldRect);
                var rect = Rectangle.Intersect(
                    screenRectF.ToPixelAlignedRect(),
                    viewportRect);
 
                if (rect.IsEmpty)
                    continue;
 
                dirty.AddDeduped(rect);
            }
        }
 
        return dirty;
    }
 
    private void PreclearScreenAreas(View view, List<Rectangle> screenRects)
    {
        if (Backbuffer is null || screenRects is null || screenRects.Count == 0)
            return;
 
        foreach (var screenRect in screenRects)
        {
            var screenRectViewport = Rectangle.Intersect(screenRect, view.GetRenderViewportTargetRectPx());
 
            if (screenRectViewport.IsEmpty || screenRectViewport.Width <= 0 || screenRectViewport.Height <= 0)
                continue;
 
            // Clear just this patch (overwrite with Backbuffer.ClearColor)
            Backbuffer.ClearRect(screenRectViewport);
 
            EnqueueForOverlappingSceneLayers(view, screenRectViewport);
        }
    }
 
    private void EnqueueForOverlappingSceneLayers(View sourceView, Rectangle clearedScreenRect)
    {
        var overlap = Rectangle.Intersect(clearedScreenRect, sourceView.GetRenderViewportTargetRectPx());
 
        if (overlap.IsEmpty)
            return;
 
        foreach (var sceneLayer in Scene.VisibleSceneLayers)
        {
            var worldRectF = sourceView.ScreenRectToWorldRect(sceneLayer, overlap);
            var worldRect = worldRectF.ToPixelAlignedRect();
 
            if (!worldRect.IsEmpty)
                sceneLayer.RefreshQueue.AddWorldRect(worldRect);
        }
    }
 
    private void RenderLayerDirtyRegions(View view, SceneLayer layer)
    {
        var refreshQueue = layer.RefreshQueue;
 
        // if this layer has no dirty regions and we are not forcing a full redraw, skip it.
        if (!refreshQueue.IsDirty)
            return;
 
        foreach (var worldRect in refreshQueue.SnapshotWorldRects())
        {
            // draw tiles/sprites/direct drawings in this world rect
            var drawables = layer.GetDrawablesInWorldRect(worldRect);
 
            // project world → screen for adapter dirty
            var screenRect = view.WorldRectToScreenRect(layer, worldRect).ToPixelAlignedRect();
 
            Backbuffer.DrawDrawables(view, drawables, screenRect);
        }
    }
 
    private int BeginPresentation(
        RectangleF bounds,
        float opacity,
        float reveal,
        EffectDirection direction,
        BackbufferBase? destination = null)
    {
        var target = destination ?? Backbuffer;
        opacity = Math.Clamp(opacity, 0f, 1f);
        reveal = Math.Clamp(reveal, 0f, 1f);
 
        if (opacity <= 0.0001f || reveal <= 0.0001f || bounds.IsEmpty)
            return 0;
 
        int saveCount = 1;
        target.Canvas.Save();
 
        if (reveal < 0.9999f)
        {
            RectangleF revealRect = EffectGeometry.GetRevealRect(bounds, direction, reveal);
            target.Canvas.ClipRect(
                revealRect.ToSKRect(),
                SKClipOperation.Intersect,
                antialias: false);
        }
 
        if (opacity < 0.9999f)
        {
            using var paint = new SKPaint
            {
                Color = new SKColor(255, 255, 255, (byte)Math.Round(opacity * 255f))
            };
 
            target.Canvas.SaveLayer(bounds.ToSKRect(), paint);
            saveCount++;
        }
 
        return saveCount;
    }
 
    private void EndPresentation(int saveCount, BackbufferBase? destination = null)
    {
        var target = destination ?? Backbuffer;
        while (saveCount-- > 0)
            target.Canvas.Restore();
    }
 
    private static RectangleF GetLayerPresentationBounds(View view, SceneLayer layer)
    {
        RectangleF viewport = view.GetRenderViewportTargetRectPx();
        PointF offset = view.GetEffectOffsetPx(layer);
 
        return new RectangleF(
            viewport.Left + offset.X,
            viewport.Top + offset.Y,
            viewport.Width,
            viewport.Height);
    }
 
    #endregion DrawRefreshQueueToBackbuffer helpers

    internal override void PresentBackbufferToAdapter()
    {
        if (RenderSurfaceAdapter is null)
            return;
 
        Backbuffer.EndFrame();
 
        if (RedrawDirtyRectangleOnly && Interlocked.Exchange(ref _presentationInvalidated, 0) == 0)
            PresentBackbufferRect();
        else
            PresentBackbufferAll();
 
        Backbuffer.ClearDirtyRectangle();
        Backbuffer.BeginFrame();
    }
 
    #region IDisposable
 
    private bool _disposed;

    protected override void Dispose(bool disposing)
    {
        if (_disposed)
            return;
 
        if (disposing)
        {
            if (_scene != null)
            {
                _scene.SceneDisposing -= OnSourceDisposing;
                _scene.UnbindRenderSurfaceHost(this);
                _scene = Scene.Empty;
            }
 
            RenderSurfaceAdapter.Resized -= OnRenderSurfaceAdapterResized;
            Backbuffer.SizeChanged -= OnBackbufferSizeChanged;
            _recordingBackbuffer?.Dispose();
            // The adapter owns GPU teardown on its context thread; keep the reference
            // valid for an already acquired replay until that callback returns.
        }
 
        _disposed = true;
 
        base.Dispose(disposing);
    }
 
    #endregion IDisposable
 
    #region private methods
 
    private void OnSourceDisposing(Scene scene)
    {
        scene.SceneDisposing -= OnSourceDisposing;
        scene.UnbindRenderSurfaceHost(this);
        _scene = Scene.Empty;
    }
 
    private void OnRenderSurfaceAdapterResized(RenderSurfaceAdapterResizedEventArgs args)
    {
        Interlocked.Exchange(ref _presentationInvalidated, 1);
        if (float.IsFinite(_deferredRenderScale) && args.NewWidth > 0 && args.NewHeight > 0)
            RequestRenderScale(_deferredRenderScale);
        if (!_resolutionEstablished && args.NewWidth > 0 && args.NewHeight > 0)
        {
            _resolutionEstablished = true;
            RequestRenderScale(Engine.Instance.Configuration.RenderScale);
        }
    }
 
    internal override void InvalidatePresentation() => Interlocked.Exchange(ref _presentationInvalidated, 1);
 
    internal override void RequestRenderScale(float scale)
    {
        if (!_resolutionEstablished || _disposed) return;
        var adapter = RenderSurfaceAdapter;
        // Zero-size requests are deferred until a valid presentation size exists.
        if (adapter.Width <= 0 || adapter.Height <= 0)
        {
            _deferredRenderScale = scale;
            return;
        }
        _deferredRenderScale = float.NaN;
        Backbuffer.RequestResize(PresentationTransform.ScaleDimension(adapter.Width, scale),
                                 PresentationTransform.ScaleDimension(adapter.Height, scale));
    }
 
    private void OnBackbufferSizeChanged(int width, int height)
    {
        float scaleX = (float)width / _logicalWidth;
        float scaleY = (float)height / _logicalHeight;
        _logicalWidth = width;
        _logicalHeight = height;
        RenderSurfaceAdapter.SetBackbufferSize(width, height);
        foreach (var view in ViewManager.Views)
        {
            var old = view.Viewport.TargetRectPx;
            view.Viewport.TargetRectPx = Rectangle.FromLTRB(
                (int)Math.Round(old.Left * scaleX), (int)Math.Round(old.Top * scaleY),
                (int)Math.Round(old.Right * scaleX), (int)Math.Round(old.Bottom * scaleY));
        }
        Scene.FullRefreshNeeded = true;
        Interlocked.Exchange(ref _presentationInvalidated, 1);
    }
 
    private void PresentBackbufferAll()
    {
        if (Backbuffer == null)
            return;
 
        var img = Backbuffer.Snapshot();
        var src = new SKRectI(0, 0, img.Width, img.Height);
        var dst = RenderSurfaceAdapter.Presentation.DestinationRect;
 
        // Post to UI thread
        Engine.Instance.UiDispatcher!.Post(() => RenderSurfaceAdapter.Present(img, src, dst));
    }
 
    private void PresentBackbufferRect()
    {
        if (Backbuffer == null)
            return;
 
        var dirty = Backbuffer.DirtyRectangle;
        if (dirty.IsEmpty)
            return;
 
        var bounds = new Rectangle(0, 0, Backbuffer.Width, Backbuffer.Height);
        var clamped = Rectangle.Intersect(dirty, bounds);
        if (clamped.IsEmpty)
            return;
 
        var img = Backbuffer.Snapshot();
 
        // Post to UI thread
        Engine.Instance.UiDispatcher!.Post(() =>
            RenderSurfaceAdapter!.Present(img, clamped.ToSKRectI(),
                PresentationTransform.Fit(img.Width, img.Height, RenderSurfaceAdapter.Width, RenderSurfaceAdapter.Height)
                    .ScreenRectToAdapterRect(clamped).ToSKRect()));
    }
 
    private void InvokePostSceneCanvasHooks(BackbufferBase? destination = null)
    {
        var target = destination ?? Backbuffer;
        var hasSurfaceHandlers = RenderBackbufferPostScene is not null;
        var hasPlugins = EnginePluginRegistry.All.Count > 0;
 
        if (!hasSurfaceHandlers && !hasPlugins)
            return;
 
        if (!target.IsGlThreadRendered)
            target.AddToBackbufferDirtyRectangle(new Rectangle(0, 0, target.Width, target.Height));
 
        if (hasSurfaceHandlers)
            RenderBackbufferPostScene?.Invoke(target.Canvas);
 
        if (hasPlugins)
            EnginePluginRegistry.InvokePostRenderCanvas(Engine.Instance, this, target.Canvas);
    }
 
    #endregion private methods
}