RenderSurface

Quick start

Use manual mode when another part of your application already owns the texture. Use managed mode when you want RenderSurface to allocate an offscreen target and ask you to draw into it.

Minimal control in XAML

<RenderSurface x:Name="PreviewSurface"
               Width="320"
               Height="180"
               Stretch="Uniform" />

Present a texture you already have

namespace InkkSlinger;

public partial class MiniMapView : UserControl
{
    private readonly RenderSurface? _previewSurface;

    public MiniMapView()
    {
        InitializeComponent();
        _previewSurface = this.FindName("PreviewSurface") as RenderSurface;
    }

    private void Publish(Texture2D texture)
    {
        _previewSurface?.Present(texture);
        _previewSurface?.RefreshSurface();
    }
}

Attach a draw handler

public partial class DiagnosticsView : UserControl
{
    private readonly RenderSurface? _surface;

    public DiagnosticsView()
    {
        InitializeComponent();
        _surface = this.FindName("PreviewSurface") as RenderSurface;
        if (_surface != null)
        {
            _surface.DrawSurface += OnDrawSurface;
        }
    }

    private void OnDrawSurface(SpriteBatch spriteBatch, Rectangle bounds)
    {
        // Draw into the supplied offscreen target.
    }
}

Choosing a mode

RenderSurface has three user-facing modes. Two are managed modes, where the control owns an offscreen target. The third is manual presentation mode, where you provide the finished surface yourself.

• Managed mode is active whenever at least one DrawSurface handler is attached or a subclass overrides OnDrawSurface.
• While managed mode is active, the managed presentation surface overrides any manual Surface value.
• If managed mode later becomes inactive, the previously assigned manual surface becomes visible again.

For deeper conceptual background, see What it is and The three modes.

Layout and sizing behavior

RenderSurface inherits from SurfacePresenterBase, so it measures from the current surface when it can and applies Stretch and StretchDirection to determine how the final texture is positioned inside its arranged slot.

• The final arranged slot can be larger or smaller than the surface's natural pixel size.
• The rendered texture is centered inside that slot after stretch scaling is computed.
• Rendering is clipped to the layout slot.
• When managed mode is arranged to a new pixel size, its offscreen resources are recreated.

Typical managed-mode layout

<Border Background="#081019"
        BorderBrush="#28445F"
        BorderThickness="1"
        Padding="12">
  <RenderSurface x:Name="GameSurface"
                 Width="560"
                 Height="392"
                 MinWidth="320"
                 MinHeight="224"
                 HorizontalAlignment="Center"
                 VerticalAlignment="Center"
                 Stretch="Uniform" />
</Border>

Stretch and direction

<RenderSurface Width="320"
               Height="180"
               Stretch="UniformToFill"
               StretchDirection="DownOnly" />

See Sizing and layout for the dedicated overview page.

Redraw and lifetime behavior

The redraw contract is small, but each method has a specific purpose. Use the method that matches how your pixels are produced.

• Presenting the same surface reference again invalidates rendering without invalidating measure.
• Presenting a different surface size invalidates measure, arrange, and render because the natural size changed.
• Managed surfaces are cleared to transparent before each redraw.
• The draw callback receives a SpriteBatch and a Rectangle in managed-surface pixel coordinates.
• Managed render targets are recreated when the graphics device changes or the arranged size changes.

Frame-driven reusable subclass

namespace InkkSlinger;

public sealed class RadarSurface : RenderSurface
{
    protected override bool IsFrameUpdateActive => true;

    protected override void OnFrameUpdate(GameTime gameTime)
    {
        _ = gameTime;
        InvalidateVisual();
    }

    protected override void OnDrawSurface(SpriteBatch spriteBatch, Rectangle bounds)
    {
        // Draw the current frame here.
    }
}

Property and API reference

RenderSurface is a presenter, not a content host. It does not expose a child content model.

Patterns and examples

Manual placeholder surface

var surface = new RenderSurface();
surface.Present(ImageSource.FromPixels(160, 90));

CPU-backed texture upload

private void TryUploadLatestFrameData()
{
    if (_framePixels == null || _surfaceTexture == null)
    {
        return;
    }

    RenderFrame(_framePixels, _surfaceTexture.Width, _surfaceTexture.Height);
    _surfaceTexture.SetData(_framePixels);
    _gameSurface?.RefreshSurface();
}

Managed event drawing

private void OnDrawGameSurface(SpriteBatch spriteBatch, Rectangle bounds)
{
    spriteBatch.Draw(_pixel, bounds, new Color(8, 12, 21));
    spriteBatch.Draw(_pixel, new Rectangle(bounds.X + 16, bounds.Y + 16, 96, 32), Color.CornflowerBlue);
}

Trigger a managed redraw

private void OnBoardChanged()
{
    _gameSurface?.InvalidateVisual();
}

Reusable subclass

public sealed class MiniMapSurface : RenderSurface
{
    protected override void OnDrawSurface(SpriteBatch spriteBatch, Rectangle bounds)
    {
        // Custom reusable drawing code.
    }
}

The repository's demo views cover both major patterns: RenderSurfaceView uses manual presentation with a texture upload path, and RenderSurfaceGpuView uses the managed DrawSurface event.

Notes and pitfalls

For the lifecycle-focused companion page, see Rules worth knowing.