Självstudie: Skapa en enkel Win2D-app

I den här handledningen introduceras några av de grundläggande ritningsfunktionerna i Win2D. Du får lära dig att:

• Lägg till Win2D i en WinUI-app (C#).
• Rita text och geometri.
• Använd filtereffekter.
• Animera ditt Win2D-innehåll.
• Följ Metodtips för Win2D.

Referera till Win2D NuGet-paketet

1. Skapa en ny WinUI-app och lägg till Nuget-paketet Microsoft.Graphics.Win2D .

Lägga till en Win2D CanvasControl i appens XAML

1. För att kunna använda Win2D behöver du någonstans att rita grafiken. I en XAML-app är det enklaste sättet att göra detta att lägga till en CanvasControl på din XAML-sida.

Innan du fortsätter, kontrollera först att alternativet projektarkitektur är inställt på x86 eller x64 och inte på Any CPU. Win2D implementeras i C++, och därför måste projekt som använder Win2D riktas mot en specifik CPU-arkitektur.

1. Gå till MainWindow.xaml i project genom att dubbelklicka på den i Solution Explorer. Då öppnas filen. För enkelhetens skull kan du dubbelklicka på XAML-knappen på fliken Designer. Detta döljer den visuella designern och reserverar allt utrymme för kodvyn.

2. Innan du lägger till kontrollen måste du först tala om för XAML var CanvasControl har definierats. För att göra detta, gå till definitionen av Window-elementet och lägg till följande direktiv: xmlns:canvas="using:Microsoft.Graphics.Canvas.UI.Xaml". Din XAML bör nu se ut så här:

<Window
    ...
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:canvas="using:Microsoft.Graphics.Canvas.UI.Xaml"
    mc:Ignorable="d">

4. Nu lägger du till ett nytt canvas:CanvasControl som ett underordnat element till rootelementet Grid. Ge kontrollen ett namn, till exempel "arbetsyta". Din XAML bör nu se ut så här:

<Grid>
    <canvas:CanvasControl x:Name="canvas"/>
</Grid>

5. Definiera sedan en händelsehanterare för händelsen Draw. CanvasControl utlöser Draw närhelst din app behöver rita eller rita om sitt innehåll. Det enklaste sättet är att låta Visual Studio Komplettera automatiskt hjälpa dig. I CanvasControl-definitionen börjar du skriva ett nytt attribut för Draw händelsehanteraren:

<canvas:CanvasControl x:Name="canvas" Draw="canvas_Draw" />

Rita din första text i Win2D

1. Nu går vi till C#-koden bakom. Öppna MainWindow.xaml.cs från Solution Explorer.

2. Överst i C#-filen finns olika namnområdesdefinitioner. Lägg till följande namnområden:

using Windows.UI;
using System.Numerics;
using Microsoft.Graphics.Canvas;
using Microsoft.Graphics.Canvas.Effects;

3. Därefter bör du se följande tomma händelsehanterare som infogades av Komplettera automatiskt:

private void canvas_Draw(
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasControl sender,
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasDrawEventArgs args)
{
}

(Om du inte använde Komplettera automatiskt i föregående steg lägger du till den här koden nu.)

4. Parametern CanvasDrawEventArgs exponerar en medlem, DrawingSession, som är av typen CanvasDrawingSession. Den här klassen innehåller de flesta grundläggande ritningsfunktionerna i Win2D: den har metoder som CanvasDrawingSession.DrawRectangle, CanvasDrawingSession.DrawImage och metoden du behöver för att rita text, CanvasDrawingSession.DrawText.

Lägg till följande kod i metoden canvas_Draw:

args.DrawingSession.DrawText("Hello, World!", 100, 100, Colors.Black);

Det första argumentet, "Hello, World!", är strängen som du vill att Win2D ska visa. De två "100"-rutorna säger till Win2D att förskjuta texten med 100 DIP:er (enhetsoberoende bildpunkter) till höger och nedåt. Colors.Black Slutligen definierar textens färg.

5. Nu är du redo att köra din första Win2D-app. Tryck på F5-tangenten för att kompilera och starta. Du bör se ett tomt fönster med "Hello, world!" i svart.

Ta bort Win2D-resurser på rätt sätt

1. Innan du fortsätter att rita andra typer av innehåll bör du först lägga till kod för att säkerställa att din app undviker minnesläckor. De flesta Win2D-program som skrivits på ett .NET språk och använder en Win2D-kontroll som CanvasControl måste följa stegen nedan. Strikt sett påverkas inte din enkla "Hello, world"-app, men det är en bra idé att följa i allmänhet.

Mer information finns i Undvika minnesläckor.

2. Öppna MainWindow.xaml och leta reda på XAML-elementet som innehåller din CanvasControl. Det bör vara det första elementet i filen.

3. Lägg till en hanterare för händelsen Unloaded. Din XAML bör se ut så här:

<Page
    ...
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:canvas="using:Microsoft.Graphics.Canvas.UI.Xaml"
    mc:Ignorable="d"
    Unloaded="Page_Unloaded">

4. Gå till MainWindow.xaml.cs och leta reda på Page_Unloaded händelsehanteraren. Lägg till följande kod:

void Page_Unloaded(object sender, RoutedEventArgs e)
{
    this.canvas.RemoveFromVisualTree();
    this.canvas = null;
}

5. Om din app innehåller flera Win2D-kontroller måste du upprepa stegen ovan för varje XAML-sida som innehåller en Win2D-kontroll. Din app har för närvarande bara en enda CanvasControl så du är klar.

Rita några former

1. Det är lika enkelt att lägga till 2D-geometri i din app. Lägg till följande kod i slutet av canvas_Draw:

args.DrawingSession.DrawCircle(125, 125, 100, Colors.Green);
args.DrawingSession.DrawLine(0, 0, 50, 200, Colors.Red);

Argumenten för dessa två metoder liknar DrawText. En cirkel definieras av en mittpunkt (125, 125), en radie (100) och en färg (grön). En linje definieras av en början (0, 0), ett slut (50, 200) och en färg (Röd).

12. Tryck nu på F5 för att köra appen. Du bör se "Hello, world!" tillsammans med en grön cirkel och röd linje.

Du kanske undrar hur du kan styra mer avancerade ritningsalternativ, till exempel linjetjocklek och bindestreck, eller mer komplexa fyllningsalternativ som att använda penslar. Win2D innehåller alla dessa alternativ och mer, och gör det enkelt att använda dem när du vill. Alla metoderna Draw(...) erbjuder många överlagringar som kan acceptera ytterligare parametrar som CanvasTextFormat (teckensnittsfamilj, storlek osv.) och CanvasStrokeStyle (streck, punkter, slutkapslar osv.). Utforska gärna API-ytan för att lära dig mer om de här alternativen.

Generera ritningsparametrar dynamiskt

1. Nu ska vi lägga till lite variation genom att rita en massa former och text med slumpmässiga färger.

Lägg till följande kod överst i din MainWindow-klass. Det här är hjälpfunktioner för att generera slumpmässiga värden som du kommer att använda när du ritar:

Random rnd = new Random();
private Vector2 RndPosition()
{
    double x = rnd.NextDouble() * 500f;
    double y = rnd.NextDouble() * 500f;
    return new Vector2((float)x, (float)y);
}

private float RndRadius()
{
    return (float)rnd.NextDouble() * 150f;
}

private byte RndByte()
{
    return (byte)rnd.Next(256);
}

2. Ändra metoden canvas_Draw så att den ritas med hjälp av dessa slumpmässiga parametrar:

private void canvas_Draw(
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasControl sender,
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasDrawEventArgs args)
{
    args.DrawingSession.DrawText("Hello, World!", RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
    args.DrawingSession.DrawCircle(RndPosition(), RndRadius(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
    args.DrawingSession.DrawLine(RndPosition(), RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
}

Låt oss dela upp hur DrawText har förändrats. "Hello, World!" förblir densamma som tidigare. Parametrarna x och y offset har ersatts med en enda System.Numerics.Vector2 som genereras av RndPosition. I stället för att använda en fördefinierad färg Color.FromArgb kan du definiera en färg med värdena A, R, G och B. A är alfa eller opacitetsnivå. I det här fallet vill du alltid ha helt ogenomskinlig (255).

DrawCircle och DrawLine fungerar på samma sätt som DrawText.

3. Slutligen omsluter du ritningskoden i en for loop. Du bör få följande kod: canvas_Draw

for (int i = 0; i < 100; i++)
{
    args.DrawingSession.DrawText("Hello, World!", RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
    args.DrawingSession.DrawCircle(RndPosition(), RndRadius(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
    args.DrawingSession.DrawLine(RndPosition(), RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
}

4. Kör appen igen. Du bör se en hel massa text, linjer och cirklar med slumpmässiga positioner och storlekar.

Tillämpa en bildeffekt på ditt innehåll

Bildeffekter, även kallade filtereffekter, är grafiska omvandlingar som tillämpas på pixeldata. Mättnad, nyansrotation och gaussisk oskärpa är några vanliga bildeffekter. Bildeffekter kan kopplas samman, vilket ger sofistikerat visuellt utseende för minimal ansträngning.

Du använder bildeffekter genom att ange en källavbildning (innehållet du börjar med), skapa en effekt som GaussianBlurEffect, ange egenskaper som BlurAmount och sedan rita effektens utdata med DrawImage.

Om du vill tillämpa en bildeffekt på text och former måste du först återge innehållet till en CanvasCommandList. Det här objektet kan användas som indata för din effekt.

2. Ändra din canvas_Draw metod så att den använder följande kod:

CanvasCommandList cl = new CanvasCommandList(sender);

using (CanvasDrawingSession clds = cl.CreateDrawingSession())
{
    for (int i = 0; i < 100; i++)
    {
        clds.DrawText("Hello, World!", RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
        clds.DrawCircle(RndPosition(), RndRadius(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
        clds.DrawLine(RndPosition(), RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
    }
}

Precis som hur du får en CanvasDrawingSession från CanvasDrawEventArgs, vilken du kan rita med, kan du skapa en CanvasDrawingSession från en CanvasCommandList. Den enda skillnaden är att när du ritar i kommandolistans ritningssession (clds) sker inte rendering direkt till CanvasControl. I stället är kommandolistan ett mellanliggande objekt som lagrar resultatet av återgivningen för senare användning.

Du kanske har lagt märke till blocket using som omsluter kommandolistan under ritningssessionen. Ritningssessioner implementerar IDisposable och måste tas bort när du är klar med återgivningen (blocket using gör detta). Den CanvasDrawingSession som du får från CanvasDrawEventArgs stängs automatiskt för dig, men du måste ta bort alla ritningssessioner som du uttryckligen skapade.

3. Definiera slutligen GaussianBlurEffect genom att lägga till följande kod i slutet av canvas_Draw metoden:

GaussianBlurEffect blur = new GaussianBlurEffect();
blur.Source = cl;
blur.BlurAmount = 10.0f;
args.DrawingSession.DrawImage(blur);

4. Kör appen igen. Du bör se rader, text och cirklar med ett suddigt utseende.

Animera din app med CanvasAnimatedControl

. Win2D ger dig möjlighet att uppdatera och animera ditt innehåll i realtid, till exempel genom att ändra suddradien för gaussisk oskärpa med varje bildruta. To do detta använder du CanvasAnimatedControl.

CanvasControl passar bäst för mestadels statiskt grafikinnehåll – det genererar Draw bara händelsen när ditt innehåll behöver uppdateras eller ritas om. Om du ständigt har ändrat innehåll bör du överväga att använda CanvasAnimatedControl i stället. De två kontrollerna fungerar mycket liknande, förutom att CanvasAnimatedControl regelbundet utlöser händelsen Draw; som standard inträffar detta 60 gånger per sekund.

2. Om du vill växla till CanvasAnimatedControlgår du till MainPage.xaml, tar bort CanvasControl-raden och ersätter den med följande XAML:

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <canvas:CanvasAnimatedControl x:Name="canvas" Draw="canvas_DrawAnimated" CreateResources="canvas_CreateResources"/>
</Grid>

Precis som med CanvasControl låter du Komplettera automatiskt skapa Draw händelsehanteraren åt dig. Som standard ger Visual Studio den här hanteraren namnet canvas_Draw_1 eftersom canvas_Draw redan finns. Här har vi bytt namn på metoden canvas_AnimatedDraw för att klargöra att detta är en annan händelse.

Dessutom hanterar du även en ny händelse, CreateResources. Låt autocomplete återigen skapa hanteraren.

Nu när din app ritas om med 60 bildrutor per sekund är det mer effektivt att skapa dina visuella Win2D-resurser en gång och återanvända dem med varje bildruta. Det är ineffektivt att skapa ett CanvasCommandList och rita in 300 element i det 60 gånger per sekund när innehållet förblir statiskt. CreateResources är en händelse som endast utlöses när Win2D fastställer att du behöver återskapa dina visuella resurser, till exempel när sidan läses in.

3. Växla tillbaka till MainPage.xaml.cs. Hitta din canvas_Draw metod som bör se ut så här:

private void canvas_Draw(
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasControl sender,
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasDrawEventArgs args)
{
    CanvasCommandList cl = new CanvasCommandList(sender);
    using (CanvasDrawingSession clds = cl.CreateDrawingSession())
    {
        for (int i = 0; i < 100; i++)
        {
            clds.DrawText("Hello, World!", RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
            clds.DrawCircle(RndPosition(), RndRadius(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
            clds.DrawLine(RndPosition(), RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
        }
    }

    GaussianBlurEffect blur = new GaussianBlurEffect();
    blur.Source = cl;
    blur.BlurAmount = 10.0f;
    args.DrawingSession.DrawImage(blur);
}

De allra flesta av den här befintliga dragningskoden behöver inte köras med varje bildruta: kommandolistan som innehåller text, rader och cirklar förblir densamma för varje bildruta och det enda som ändras är radien för oskärpa. Därför kan du flytta den här "statiska" koden till CreateResources.

För att göra detta, klipper du först ut (CTRL+X) hela innehållet i canvas_Draw, förutom den allra sista raden (args.DrawingSession.DrawImage(blur);). Nu kan du ta bort resten av canvas_Draw eftersom det inte längre behövs: kom ihåg att det CanvasAnimatedControl har en egen distinkt Draw händelse.

4. Hitta den automatiskt genererade canvas_CreateResources metoden:

private void canvas_CreateResources(
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasAnimatedControl sender, 
    Microsoft.Graphics.Canvas.UI.CanvasCreateResourcesEventArgs args)
{}

Klistra in (CTRL+V) din tidigare klippta kod i den här metoden. Flytta sedan deklarationen utanför GaussianBlurEffect metodtexten så att variabeln blir medlem i klassen MainPage. Koden bör nu se ut så här:

GaussianBlurEffect blur;
private void canvas_CreateResources(
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasAnimatedControl sender,
    Microsoft.Graphics.Canvas.UI.CanvasCreateResourcesEventArgs args)
{
    CanvasCommandList cl = new CanvasCommandList(sender);
    using (CanvasDrawingSession clds = cl.CreateDrawingSession())
    {
        for (int i = 0; i < 100; i++)
        {
            clds.DrawText("Hello, World!", RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
            clds.DrawCircle(RndPosition(), RndRadius(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
            clds.DrawLine(RndPosition(), RndPosition(), Color.FromArgb(255, RndByte(), RndByte(), RndByte()));
        }
    }

    blur = new GaussianBlurEffect()
    {
        Source = cl,
        BlurAmount = 10.0f
    };
}

5. Nu kan du animera gaussiska oskärpa. Leta upp canvas_DrawAnimated metoden och lägg till följande kod:

private void canvas_DrawAnimated(
    Microsoft.Graphics.Canvas.UI.Xaml.ICanvasAnimatedControl sender,
    Microsoft.Graphics.Canvas.UI.Xaml.CanvasAnimatedDrawEventArgs args)
{
    float radius = (float)(1 + Math.Sin(args.Timing.TotalTime.TotalSeconds)) * 10f;
    blur.BlurAmount = radius;
    args.DrawingSession.DrawImage(blur);
}

Detta läser av den totala tid som förflutit, tillhandahållen av CanvasAnimatedDrawEventArgs, och använder den för att beräkna önskad mängd oskärpa; sinusfunktionen ger en intressant variation över tid. Slutligen renderas GaussianBlurEffect.

6. Kör appen för att se att det suddiga innehållet ändras över tid.

Grattis till att du har slutfört den här snabbstartsguiden! Förhoppningsvis har du sett hur du kan använda Win2D för att skapa en omfattande, animerad visuell scen med bara några rader C# och XAML-kod.