Créer une application Win2D simple

Ce tutoriel présente quelques-unes des fonctionnalités de base de Win2D. Vous découvrirez comment effectuer les actions suivantes :

• Ajoutez Win2D à un projet C# XAML Windows.
• Dessinez du texte et des formes géométriques.
• Appliquez des effets de filtre.
• Animez votre contenu Win2D.
• Suivez les meilleures pratiques relatives à Win2D.

Configurer votre ordinateur de développement

Assurez-vous de configurer votre ordinateur avec tous les outils nécessaires :

• Installer Visual Studio
  • Inclure la plateforme Windows universelle (UWP) ou le Kit de développement logiciel Windows (Kit SDK Windows) selon vos besoins, 17763+
• Si vous utilisez UWP, veiller également à activer le mode développeur

Créer un projet Win2D

Suivez les étapes du Démarrage rapide Win2D « Hello, World! » pour créer un projet en utilisateur Win2D et ajoutez une référence au package NuGet Win2D. Vous pouvez utiliser WinUI 3 (Kit de développement logiciel (SDK) d’application Windows) ou le plateforme Windows universelle (UWP).

Ajouter un CanvasControl Win2D au code XAML de votre application

1. Pour utiliser Win2D, vous avez besoin d’un emplacement pour dessiner vos graphismes. Dans une application XAML, la méthode la plus simple consiste à ajouter un CanvasControl à votre page XAML.

Avant de continuer, vérifiez d’abord que l’option Architecture du projet est définie sur x86 ou x64 et non sur Any CPU. Win2D étant implémenté en C++, les projets qui utilisent Win2D doivent donc être ciblés sur une architecture de processeur spécifique.

1. Accédez à MainPage.xaml dans votre projet en double-cliquant dessus dans l’Explorateur de solutions. Le fichier s’ouvre. Pour des raisons pratiques, vous pouvez double-cliquer sur le bouton XAML sous l’onglet Concepteur. Ceci masque le concepteur visuel et réserve toute la place disponible à l’affichage du code.

2. Avant d’ajouter le contrôle, vous devez d’abord indiquer à XAML où CanvasControl est défini. Pour ce faire, accédez à la définition de l’élément Page et ajoutez l’instruction suivante : xmlns:canvas="using:Microsoft.Graphics.Canvas.UI.Xaml". Votre code XAML doit maintenant ressembler à ceci :

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

4. À présent, ajoutez un nouveau canvas:CanvasControl en tant qu’élément enfant à l’élément Grid racine. Donnez un nom au contrôle, par exemple « canevas ». Votre code XAML doit maintenant ressembler à ceci :

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <canvas:CanvasControl x:Name="canvas"/>
</Grid>

5. Définissez ensuite un gestionnaire d’événements pour l’événement Dessin. CanvasControl déclenche Draw chaque fois que votre application doit dessiner ou redessiner son contenu. Le moyen le plus simple consiste à faire appel à la fonctionnalité d’autocomplétion de Visual Studio. Dans la définition de CanvasControl, commencez à taper un nouvel attribut pour le gestionnaire d’événements Draw :

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

Remarque

Une fois dans Draw=", Visual Studio doit vous demander l’autorisation de remplir automatiquement la bonne définition pour le gestionnaire d’événements. Appuyez sur Tab pour accepter le gestionnaire d’événements par défaut de Visual Studio. Par ailleurs, une méthode de gestionnaire d’événements correctement mise en forme est ajoutée automatiquement à votre code-behind (`MainPage.xaml.cs`). Ne vous inquiétez pas si vous n’avez pas utilisé l’autocomplétion, car vous pourrez ajouter manuellement la méthode de gestionnaire d’événements à l’étape suivante.

Dessiner votre premier texte dans Win2D

1. Passons maintenant au code-behind C#. Ouvrez MainPage.xaml.cs à partir de l’Explorateur de solutions.

2. En haut du fichier C# figurent différentes définitions d’espace de noms. Ajoutez les espaces de noms suivants :

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

3. Vous devez également voir le gestionnaire d’événements vide suivant qui a été inséré par l’autocomplétion :

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

(Si vous n’avez pas utilisé l’autocomplétion à l’étape précédente, ajoutez ce code maintenant.)

4. Le paramètre CanvasDrawEventArgs expose un membre, DrawingSession, qui est de type CanvasDrawingSession. Cette classe fournit la plupart des fonctionnalités de dessin de base dans Win2D : elle a des méthodes telles que CanvasDrawingSession.DrawRectangle, CanvasDrawingSession.DrawImage et la méthode dont vous avez besoin pour dessiner du texte, CanvasDrawingSession.DrawText.

Ajoutez le code suivant à la méthode canvas_Draw :

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

Le premier argument, "Hello, World!", est la chaîne que vous souhaitez que Win2D affiche. Les deux valeurs 100 indiquent à Win2D de décaler ce texte de 100 DIP (pixels indépendants des appareils) vers la droite et vers le bas. Enfin, Colors.Black définit la couleur du texte.

5. Vous êtes maintenant prêt à exécuter votre première application Win2D. Appuyez sur F5 pour compiler et lancer l’application. Vous devriez voir une fenêtre vide avec « Hello, world! » en noir.

Supprimer correctement les ressources Win2D

1. Avant de continuer à dessiner d’autres types de contenu, vous devez d’abord ajouter du code pour vous assurer que votre application évite les fuites de mémoire. La plupart des applications Win2D écrites dans un langage .NET et utilisant un contrôle Win2D comme CanvasControl doivent suivre les étapes ci-dessous. À proprement parler, votre application « Hello, world » de base n’est pas affectée, mais il est recommandé de suivre cette bonne pratique.

Pour plus d’informations, consultez Éviter les fuites de mémoire.

2. Ouvrez MainPage.xaml et recherchez l’élément Page XAML qui contient votre CanvasControl. Il doit s’agir du premier élément dans le fichier.

3. Ajoutez un gestionnaire pour l’événement Unloaded. Votre code XAML doit ressembler à ceci :

<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. Accédez à MainPage.xaml.cs et recherchez le gestionnaire d’événements Page_Unloaded. Ajoutez le code suivant :

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

5. Si votre application contient plusieurs contrôles Win2D, vous devez répéter les étapes ci-dessus pour chaque page XAML contenant un contrôle Win2D. Votre application n’ayant actuellement qu’un seul CanvasControl, vous avez terminé.

Dessiner des formes

1. Vous pouvez tout aussi facilement ajouter une géométrie 2D à votre application. Ajoutez le code suivant à la fin de canvas_Draw :

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

Les arguments de ces deux méthodes sont similaires à DrawText. Un cercle est défini par un point central (125, 125), un rayon (100) et une couleur (vert). Une ligne est définie par un début (0, 0), une fin (50, 200) et une couleur (rouge).

12. Appuyez maintenant sur F5 pour exécuter l’application. Vous devriez voir « Hello, world! » avec un cercle vert et une ligne rouge.

Vous vous demandez peut-être comment contrôler des options de dessin plus avancées, telles que l’épaisseur des lignes et les tirets, ou des options de remplissage plus complexes comme celles utilisant des pinceaux. Win2D fournit toutes ces options et bien d’autres, et vous pouvez les utiliser facilement quand vous le souhaitez. Toutes les méthodes Draw(...) offrent de nombreuses surcharges qui peuvent accepter des paramètres supplémentaires tels que CanvasTextFormat (famille de polices, taille, etc.) et CanvasStrokeStyle (tirets, points, extrémités, etc.). N’hésitez pas à explorer la surface de l’API pour en savoir plus sur ces options.

Générer dynamiquement des paramètres de dessin

1. Introduisons à présent un peu de variété en dessinant un ensemble de formes et du texte avec des couleurs aléatoires.

Ajoutez le code suivant en haut de votre classe MainPage. Il s’agit d’une fonctionnalité d’assistance qui permet de générer des valeurs aléatoires que vous utiliserez pour dessiner :

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. Modifiez votre méthode canvas_Draw pour dessiner avec ces paramètres aléatoires :

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()));
}

Examinons de plus près les changements apportés à DrawText. "Hello, World!" n’a pas changé. Les paramètres de décalage x et y ont été remplacés par un seul System.Numerics.Vector2 qui est généré par RndPosition. Enfin, au lieu d’utiliser une couleur prédéfinie, Color.FromArgb vous permet de définir une couleur à l’aide de valeurs A, R, G et B. A correspond à alpha, c’est-à-dire le niveau d’opacité. Dans ce cas, vous voulez toujours une opacité totale (255).

DrawCircle et DrawLine fonctionnent de manière similaire à DrawText.

3. Enfin, wrappez votre code de dessin dans une boucle for . Vous devriez obtenir le code canvas_Draw suivant :

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. Réexécutez l’application. Vous devriez voir du texte, des lignes et des cercles avec des positions et des tailles aléatoires.

Appliquer un effet d’image à votre contenu

Les effets d’image, également appelés effets de filtre, sont des transformations graphiques appliquées aux données de pixels. La saturation, la rotation de teinte et le flou gaussien sont quelques effets d’image courants. Les effets d’image peuvent être chaînés ensemble pour produire une apparence visuelle sophistiquée avec un minimum d’effort.

Pour utiliser des effets d’image, fournissez une image source (votre contenu de départ), créez un effet tel que GaussianBlurEffect, en définissant des propriétés telles que BlurAmount, puis dessinez la sortie de l’effet avec DrawImage.

Pour appliquer un effet d’image à votre texte et à vos formes, vous devez d’abord afficher ce contenu dans une CanvasCommandList. Cet objet peut être utilisé comme entrée de votre effet.

2. Modifiez votre méthode canvas_Draw pour utiliser le code suivant :

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()));
    }
}

De la même manière que vous obtenez un CanvasDrawingSession à partir de CanvasDrawEventArgs avec lequel vous pouvez dessiner, vous pouvez créer un CanvasDrawingSession à partir d’un CanvasCommandList. La seule différence est que lorsque vous dessinez dans la session de dessin de la liste de commandes (clds), vous n’effectuez pas directement le rendu sur le CanvasControl. Au lieu de cela, la liste de commandes est un objet intermédiaire qui stocke les résultats du rendu pour une utilisation ultérieure.

Vous avez peut-être remarqué le bloc using qui wrappe la session de dessin de la liste de commandes. Les sessions de dessin implémentent IDisposable et doivent être supprimées au terme du rendu (ce dont se charge le bloc using). La session (CanvasDrawingSession) que vous obtenez de CanvasDrawEventArgs est automatiquement fermée pour vous, mais vous devez supprimer toutes les sessions de dessin que vous avez créées explicitement.

3. Enfin, définissez le GaussianBlurEffect en ajoutant le code suivant à la fin de la méthode canvas_Draw :

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

4. Réexécutez l’application. Vous devriez voir vos lignes, votre texte et vos cercles avec une apparence floue.

Animer votre application avec CanvasAnimatedControl

. Win2D vous permet de mettre à jour et d’animer votre contenu en temps réel, par exemple en modifiant le rayon du flou gaussien à chaque image. Pour ce faire, vous allez utiliser CanvasAnimatedControl.

CanvasControl est mieux adapté au contenu graphique principalement statique : il ne déclenche l’événement Draw que lorsque votre contenu doit être mis à jour ou redessiné. Si votre contenu change continuellement, envisagez plutôt d’utiliser CanvasAnimatedControl. Les deux contrôles fonctionnent de façon très similaire, à ceci près que CanvasAnimatedControl déclenche l’événement Draw de façon périodique (par défaut, il est appelé 60 fois par seconde).

2. Pour passer à CanvasAnimatedControl, accédez à MainPage.xaml, supprimez la ligne CanvasControl et remplacez-la par le code XAML suivant :

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

Tout comme avec CanvasControl, laissez Remplissage autom. créer le gestionnaire d’événements Draw pour vous. Par défaut, Visual Studio nomme ce gestionnaire canvas_Draw_1, car canvas_Draw existe déjà ; ici, nous avons renommé la méthode canvas_AnimatedDraw pour indiquer clairement qu’il s’agit d’un événement différent.

De plus, vous gérez également un nouvel événement, CreateResources. Là encore, laissez l’autocomplétion créer le gestionnaire pour vous.

Maintenant que votre application sera redessinée à 60 images par seconde, il est plus efficace de créer vos ressources visuelles Win2D une seule fois et de les réutiliser avec chaque image. Il est inefficace de créer un CanvasCommandList et d’y dessiner 300 éléments 60 fois par seconde lorsque le contenu reste statique. CreateResources est un événement qui est déclenché uniquement lorsque Win2D détermine que vous devez recréer vos ressources visuelles, par exemple quand la page est chargée.

3. Revenez à MainPage.xaml.cs. Recherchez votre méthode canvas_Draw, qui doit ressembler à ceci :

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);
}

La grande majorité de ce code de dessin existant n’a pas besoin d’être exécuté avec chaque image : la liste de commandes contenant le texte, les lignes et les cercles reste la même avec chaque image, la seule chose qui change étant le rayon du flou. Vous pouvez donc déplacer ce code « statique » dans CreateResources.

Pour ce faire, commencez par couper (Ctrl+X) l’intégralité du contenu canvas_Draw, à l’exception de la dernière ligne (args.DrawingSession.DrawImage(blur);). Vous pouvez maintenant supprimer le reste de canvas_Draw, car il n’est plus nécessaire. En effet, CanvasAnimatedControl a son propre événement Draw distinct.

4. Recherchez la méthode canvas_CreateResources générée automatiquement :

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

Collez (Ctrl+V) le code précédemment coupé dans cette méthode. Ensuite, déplacez la déclaration de GaussianBlurEffect en dehors du corps de la méthode afin que la variable devienne membre de la classe MainPage. À présent, votre code doit ressembler à ce qui suit :

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. Vous pouvez maintenant animer le flou gaussien. Recherchez la méthode canvas_DrawAnimated et ajoutez le code suivant :

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);
}

Ce code lit le temps total écoulé fourni par CanvasAnimatedDrawEventArgs et l’utilise pour calculer la quantité de flou souhaité ; la fonction sinus fournit une variation intéressante au fil du temps. Enfin, GaussianBlurEffect est affiché.

6. Exécutez l’application pour voir le contenu flou changer au fil du temps.

Félicitations ! Vous avez terminé ce tutoriel de démarrage rapide. Vous avez vu comment utiliser Win2D pour créer une scène visuelle riche et animée avec seulement quelques lignes de code C# et XAML.