Image

Quick start

Use Image when you already have an ImageSource contract for a texture or URI-backed asset and you want a normal framework element that participates in layout, alignment, clipping, styling, and opacity.

Minimal XAML image

<Image Width="96"
       Height="96"
       Source="avatars/player-1"
       Stretch="Uniform" />

Thumbnail crop-style presentation

<Border Width="160"
        Height="96"
        BorderBrush="#35516B"
        BorderThickness="1">
  <Image Source="art/cards/mission-brief"
         Stretch="UniformToFill" />
</Border>

Assign a texture in code

namespace InkkSlinger;

public partial class ProfileView : UserControl
{
    private readonly Image? _portrait;

    public ProfileView()
    {
        InitializeComponent();
        _portrait = this.FindName("PortraitImage") as Image;
    }

    public void SetPortrait(Texture2D texture)
    {
        _portrait!.Source = ImageSource.FromTexture(texture);
    }
}

Source model

Image exposes a single content-like property: Source. The property type is ImageSource, not a WPF bitmap class. The control inherits its entire presentation contract from that source object.

• If Source is null, the control has no intrinsic size and draws nothing.
• If a URI-backed source cannot resolve to a valid pixel-sized surface, the control behaves as unresolved and does not contribute intrinsic image size.
• The control clears its cached URI resolution when Source changes.

Raw XAML string to URI-backed source

<Image Source="ui/icons/warning"
       Width="20"
       Height="20" />

That markup is treated as an ImageSource value by the XAML loader, which converts the raw string into ImageSource.FromUri(...) before the property is applied.

Configure a URI resolver once

ImageSource.UriSourceResolver = uri =>
    ImageSource.FromTexture(Content.Load<Texture2D>(uri));

Layout and sizing behavior

Image inherits from SurfacePresenterBase. Measure and arrange use the resolved source's natural pixel size, then apply Stretch and StretchDirection to fit the image into the arranged slot.

• Stretch="None" keeps the natural pixel size.
• Stretch="Fill" scales width and height independently to fill the slot.
• Stretch="Uniform" preserves aspect ratio and fits entirely inside the slot.
• Stretch="UniformToFill" preserves aspect ratio and fills the slot, which can crop against the layout clip.
• StretchDirection="UpOnly" prevents downscaling below 1x.
• StretchDirection="DownOnly" prevents upscaling above 1x.

Preserve the whole image

<Image Width="320"
       Height="180"
       Source="art/loading-screen"
       Stretch="Uniform"
       StretchDirection="Both" />

Avoid enlarging small icons

<Border Width="48"
        Height="48"
        Background="#101822">
  <Image Source="ui/icons/pin"
         Stretch="Uniform"
         StretchDirection="DownOnly" />
</Border>

In that second example, a smaller icon can shrink to fit but will not be scaled up beyond its natural pixel size.

Rendering behavior

The render path is intentionally narrow. Image draws one texture into one computed rectangle. There is no built-in tiling, brush model, nine-slice scaling, or child composition behavior on this control.

• Source changes invalidate both measure and rendering through the dependency property metadata on Source.
• URI-backed resolution is cached per requested source instance until the Source property changes.
• The final texture rectangle is centered inside the arranged slot.

Fade an image with normal element opacity

<Image Source="gallery/cover-01"
       Width="240"
       Height="135"
       Stretch="UniformToFill"
       Opacity="0.72" />

Property reference

Image is a presenter, not a content host. It does not expose a child collection, overlay slot, or template-owned drawing callback like RenderSurface.

Patterns and examples

Avatar inside framed chrome

<Border Width="88"
        Height="88"
        BorderBrush="#4FC7C1"
        BorderThickness="1"
        Padding="4">
  <Image x:Name="PortraitImage"
         Source="avatars/scout"
         Stretch="UniformToFill" />
</Border>

Banner art that fills the card

<Grid Width="320" Height="140">
  <Image Source="banners/season-05"
         Stretch="UniformToFill"
         Opacity="0.85" />
  <Border Background="#66081119" />
  <TextBlock Text="Season Five"
             Margin="16"
             VerticalAlignment="Bottom" />
</Grid>

Reserve layout while the asset loads

var image = new Image
{
    Width = 320,
    Height = 180,
    Source = ImageSource.FromPixels(320, 180)
};

// Later, once the texture is available:
image.Source = ImageSource.FromTexture(texture);

Swap sources without changing the view structure

private void ShowPreview(Texture2D texture)
{
    PreviewImage.Source = ImageSource.FromTexture(texture);
}

private void ClearPreview()
{
    PreviewImage.Source = null;
}

Bind a view-model-provided source

<Image Width="200"
       Height="112"
       Source="{Binding SelectedPreview}"
       Stretch="Uniform" />

That binding works when SelectedPreview resolves to an ImageSource instance. If your view model exposes a string URI instead, convert it before binding or expose an ImageSource-typed property directly.

Notes and pitfalls