Premiers pas avec Zdog

Cette page vous guide pas à pas dans la conception, l'affichage et l'animation d'un modèle 3D simple avec Zdog.

HTML

Zdog dessine sur un élément <canvas> ou <svg>. Les attributs width et height définissent sa taille.

<canvas class="zdog-canvas" width="240" height="240"></canvas>

Sur ce portail, Zdog est déjà installé. Il suffit d'ajouter le fichier JavaScript de Zdog dans le <head> de votre page, puis une balise <script> pour le fichier JS de votre démo.

<script src="/libs/zdog.min.js"></script>
<script src="zdog-demo.js"></script>

Première démo statique

Commençons par une démo de base, sans animation.

// zdog-demo.js

// créer l'illustration
let illo = new Zdog.Illustration({
  // définir le canvas avec un sélecteur
  element: '.zdog-canvas',
});

// ajouter un cercle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 80,
  stroke: 20,
  color: '#636',
});

// mettre à jour et afficher
illo.updateRenderGraph();

Décortiquons ce code. L'API de Zdog consiste principalement à créer des instances de classes Zdog.

Illustration est la classe de plus haut niveau : elle gère l'élément <canvas> ou <svg>, contient toutes les formes de la scène et les affiche dans l'élément. Nous désignons l'élément de rendu en donnant à element le sélecteur correspondant, '.zdog-canvas'. L'instance d'Illustration est ensuite stockée dans la variable illo.

Ellipse est une classe de forme. Nous l'ajoutons à la scène avec addTo: illo. Le cercle est donc un enfant de illo : il fait partie de son graphe de descendants. Les autres propriétés définissent sa taille, son épaisseur et sa couleur : diameter: 80, stroke: 20, color: '#636'.

Enfin, pour afficher la scène, nous appelons illo.updateRenderGraph(), qui met à jour toutes les propriétés d'affichage puis dessine les formes dans l'élément.

Et nous obtenons… un cercle violet de 80 px de large. Passionnant !

Animation

Pour animer notre scène, il faut redessiner illo à chaque image.

function animate() {
  // faire pivoter illo à chaque image
  illo.rotate.y += 0.03;
  illo.updateRenderGraph();
  // animer l'image suivante
  requestAnimationFrame( animate );
}
// démarrer l'animation
animate();

Nous enveloppons donc illo.updateRenderGraph() dans une boucle requestAnimationFrame. Nous pouvons maintenant modifier la scène et voir les changements s'animer. Ici, nous changeons la rotation de la scène en augmentant progressivement illo.rotate.y.

Et maintenant le cercle animé est… plutôt terne. Il tourne bel et bien, mais, seul et placé au centre exact, l'effet visuel est faible. Ajoutons une autre forme, un Rect, et positionnons les formes dans l'espace 3D.

// cercle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 80,
  // positionner plus près
  translate: { z: 40 },
  stroke: 20,
  color: '#636',
});

// carré
new Zdog.Rect({
  addTo: illo,
  width: 80,
  height: 80,
  // positionner plus loin
  translate: { z: -40 },
  stroke: 12,
  color: '#E62',
  fill: true,
});

Voilà qui devient intéressant. Les formes sont positionnées grâce à translate. Le cercle a translate: { z: 40 } : il est donc déplacé de 40 pixels vers l'avant. Le carré, lui, est reculé de 40 pixels. Les formes étant séparées l'une de l'autre, elles tournent en orbite autour du centre lors de la rotation.

Zoom

Zdog demande de définir beaucoup de nombres. Il est plus agréable de garder des nombres petits. Définir zoom met à l'échelle toute la scène de façon proportionnelle.

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  // zoom x4
  zoom: 4,
});

new Zdog.Ellipse({
  diameter: 20,
  translate: { z: 10 },
  stroke: 5,
  ...
});

new Zdog.Rect({
  width: 20,
  height: 20,
  translate: { z: -10 },
  stroke: 3,
  ...
});

Rotation par glissement

Activez la rotation par glissement (drag) en définissant dragRotate: true sur l'Illustration.

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 4,
  // activer la rotation de la scène par glissement
  dragRotate: true,
});

Nous pouvons rétablir la rotation automatique et l'arrêter dès que le glissement commence, grâce à onDragStart.

// variable indicatrice de rotation
let isSpinning = true;

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 4,
  dragRotate: true,
  // arrêter la rotation au début du glissement
  onDragStart: function() {
    isSpinning = false;
  },
});

// ajouter des formes...

function animate() {
  // faire pivoter
  if ( isSpinning ) {
    illo.rotate.y += 0.03;
  }
  illo.updateRenderGraph();
  requestAnimationFrame( animate );
}
animate();

Voilà pour les bases de l'affichage d'un modèle 3D avec Zdog. Vous êtes maintenant prêt à en apprendre davantage sur la modélisation et les formes de Zdog.

Traduction française de la documentation de Zdog (licence MIT) – https://zzz.dog