Chapitre -99 · Bibliothèque de formes

Une boîte à formes pour tes PNJ

Sphères, capsules, cônes, ressorts, formes tournées — de quoi assembler n'importe quel personnage, sans Blender ni fichier .glb.

Dans ↘ Shapes tu as écrit chaque sommet à la main. Dans ↘ SDF — math, tu as dessiné des formes rondes sans aucun triangle. Ici on fait le pont : des formes rondes, mais en vrais triangles, que le GPU rastérise comme n'importe quel mesh.

L'idée :

Tu vas peupler le monde de Personne Non Joueur : des personnages qui se déplacent, regardent, réagissent. Un PNJ, c'est une maquette : un corps, une tête, des yeux, des bras, un chapeau. Chaque pièce est une forme simple ; c'est leur assemblage (et leur animation) qui donne le personnage.

Ce chapitre construit la boîte à outils : MeshBuilder.hpp. Une bibliothèque, pas un objet précis — le drone en est le premier utilisateur, chaque PNJ en sera un autre.

Structure du projet attendue

MSLearn/ ├── Renderer/ │ └── MathFunction.hpp ← la bibliothèque du chapitre précédent MeshBuilder_shared.h └── …

Les choix qui en font une bibliothèque

Tout dans un header, tout en inline

Beaucoup de modules de ta future application l'incluront. Si basisAround() était une fonction normale écrite dans un .hpp, chaque .cpp qui l'inclut en recevrait une copie, et l'éditeur de liens refuserait : deux définitions du même nom. inline lui dit « c'est la même partout, garde-en une ». Les fonctions d'un template le sont automatiquement, et inline constexpr fait pareil pour les constantes.

Nos axes orthogonaux

Équivalent à nos axes de caméras.

/// C++ — MeshBuilder.hpp — update:23/10/26
#ifndef MeshBuilder_hpp
#define MeshBuilder_hpp

#include <algorithm>
#include <cmath>
#include <cstdio>

constexpr simd::float3 kUp    = { 0.f, 1.f, 0.f }; // ↑
constexpr simd::float3 kAxisX = { 1.f, 0.f, 0.f }; // →
constexpr simd::float3 kAxisZ = { 0.f, 0.f, 1.f }; // ↗︎

#endif /* MeshBuilder_hpp */
/// C++ — MeshBuilder.hpp — update:23/10/26
struct ProfilePoint
{ // Un point du profil d'un lathe : à quelle distance de l'axe, à quelle hauteur
  float radius;
  float height;
};
/// C++ — MeshBuilder.hpp — update:23/10/26
inline void basisAround(simd::float3 axis, simd::float3& tangent, simd::float3& bitangent)
{ // Deux directions perpendiculaires à `axis` (et entre elles) : le plan dans lequel on fait tourner un cercle.
  tangent   = simd::normalize(simd::cross(std::abs(axis.y) > 0.9f ? kAxisX : kUp, axis));
  bitangent = simd::cross(axis, tangent);
} // La référence change quand l'axe est presque vertical, sinon le produit vectoriel tomberait à zéro

inline float signedPow(float value, float exponent)
{ // Puissance qui garde le signe : signedPow(-0.5, 2) = -0.25 (sert au superellipsoïde).
  if (std::abs(value) < 1e-6f)
    return 0.f;
  return std::copysign(std::pow(std::abs(value), exponent), value);
} // En flottant, sin(π) vaut -8.7e-8 et pas 0 : à la puissance 0.2 ça ferait 0.04, et le pôle resterait ouvert

Le fichier partagé

/// C++ — MeshBuilder_shared.h — update:23/10/26
#ifndef MeshBuilder_shared_h
#define MeshBuilder_shared_h

#include <simd/simd.h>

struct MeshBuilderVertex
{
  simd::float3 position;    // espace modèle de la pièce
  simd::float3 normal;
  uint32_t     part;
  uint32_t     material;
};

#endif /* MeshBuilder_shared_h */

Le code complet

La bibliothèque d'abord, puis le drone qui s'en sert. On démonte tout juste après.

/// C++ — MeshBuilder.hpp — update:23/10/26
#include "../includes/SharedGPU/MeshBuilder_shared.h"
around : le tour de la forme (0 → 1 = 0 → 360°), comme la longitude sur un globe along : le long de la forme (sphère : du pôle nord au pôle sud ; tore : le tour du tube) segmentsAround / segmentsAlong : en combien de morceaux on découpe chaque sens. Plus il y en a, plus c'est rond (et plus il y a de triangles). // On obtient une grille de (segmentsAround + 1) × (segmentsAlong + 1) sommets ; // chaque case de la grille devient un quad = 2 triangles. // La fonction `evaluate(around, along, position, normal)` dit où tombe chaque sommet. // // Orientation : chaque triangle est retourné si besoin pour que son produit vectoriel pointe // du même côté que les normales de ses sommets (vers l'extérieur). Avec la caméra main gauche // du projet, ça donne un sens horaire à l'écran = la face avant par défaut de Metal. // // Vertex : n'importe quel type de sommet qui a position, normal (simd::float3), part et material (uint32_t). // Le drone a le sien, chaque PNJ peut avoir le sien : la bibliothèque ne connaît que ces quatre champs.
/// C++ — MeshBuilder.hpp — update:23/10/26
struct MeshBuilder
{
  std::vector<MeshBuilderVertex> vertices;
  std::vector<uint32_t>          indices;

  void buildTriangle(uint32_t first, uint32_t second, uint32_t third)
  {
    const simd::float3 origin     = vertices[first].position;
    const simd::float3 faceNormal = simd::cross(vertices[second].position - origin,
                                                vertices[third].position - origin);
    if (simd::length_squared(faceNormal) < 1e-14f)
      return; // triangle aplati en un trait ou un point (aux pôles des sphères)
    const simd::float3 outward = vertices[first].normal + vertices[second].normal + vertices[third].normal;
    if (simd::dot(faceNormal, outward) < 0.f)
      std::swap(second, third);
    indices.insert(indices.end(), { first, second, third });
  }

  template <class Surface>
  void buildSurface(int segmentsAround, int segmentsAlong, uint32_t part, uint32_t material, Surface&& evaluate)
  { // 1. La grille de sommets
    const auto firstVertex = (uint32_t)vertices.size();
    for (int alongIndex = 0; alongIndex <= segmentsAlong; ++alongIndex)
      for (int aroundIndex = 0; aroundIndex <= segmentsAround; ++aroundIndex)
      {
        MeshBuilderVertex vertex{};
        evaluate((float)aroundIndex / (float)segmentsAround, (float)alongIndex / (float)segmentsAlong,
                 vertex.position, vertex.normal);
        vertex.part     = part;
        vertex.material = material;
        vertices.push_back(vertex);
      }
      // 2. Deux triangles par case : le sommet courant, son voisin, et les deux de la rangée suivante
      const uint32_t verticesPerRow = (uint32_t)segmentsAround + 1;
      for (uint32_t alongIndex = 0; alongIndex < (uint32_t)segmentsAlong; ++alongIndex)
        for (uint32_t aroundIndex = 0; aroundIndex < (uint32_t)segmentsAround; ++aroundIndex)
        {
          const uint32_t current   = firstVertex + alongIndex * verticesPerRow + aroundIndex;
          const uint32_t next      = current + 1;
          const uint32_t below     = current + verticesPerRow;
          const uint32_t belowNext = below + 1;
          buildTriangle(current, next, belowNext);
          buildTriangle(current, belowNext, below);
        }
  }

  // Sphère étirée (rayons différents en x, y, z) : la base de toutes les formes rondes
  void buildEllipsoid(simd::float3 center, simd::float3 radii, uint32_t part, uint32_t material, int segmentsAround = 28)
  {
    buildSurface(segmentsAround, segmentsAround / 2, part, material,
            [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float longitude = around * 2.f * (float)M_PI; // tour complet
      const float latitude  = along * (float)M_PI; // pôle nord (0) → pôle sud (π)
      const simd::float3 direction = { std::sin(latitude) * std::cos(longitude), std::cos(latitude),
                                       std::sin(latitude) * std::sin(longitude) };
      position = center + direction * radii;
      normal   = simd::normalize(direction / radii); // une sphère étirée a des normales « écrasées » à l'inverse
    });
  }

  // Anneau (donut) autour de `axis` : ringRadius = rayon de l'anneau, tubeRadius = épaisseur du tube
  void buildTorus(simd::float3 center, simd::float3 axis, float ringRadius,
             float tubeRadius, uint32_t part, uint32_t material)
  {
    axis = simd::normalize(axis);
    // Deux directions perpendiculaires à l'axe : le plan dans lequel l'anneau tourne
    const simd::float3 tangent   = simd::normalize(simd::cross(std::abs(axis.y) > 0.9f ? kAxisX : kUp, axis));
    const simd::float3 bitangent = simd::cross(axis, tangent);
    buildSurface(32, 12, part, material, [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float ringAngle = around * 2.f * (float)M_PI;   // où l'on est sur l'anneau
      const float tubeAngle = along * 2.f * (float)M_PI;    // où l'on est autour du tube
      const simd::float3 ringDirection = tangent * std::cos(ringAngle) + bitangent * std::sin(ringAngle);
      normal   = ringDirection * std::cos(tubeAngle) + axis * std::sin(tubeAngle);
      position = center + ringDirection * ringRadius + normal * tubeRadius;
    });
  }

  // Cylindre aux bouts arrondis, de start à end : une sphère coupée à l'équateur dont on écarte les deux moitiés
  void buildCapsule(simd::float3 start, simd::float3 end, float radius, uint32_t part, uint32_t material)
  {
    const simd::float3 axis      = simd::normalize(end - start);
    const simd::float3 tangent   = simd::normalize(simd::cross(std::abs(axis.y) > 0.9f ? kAxisX : kUp, axis));
    const simd::float3 bitangent = simd::cross(axis, tangent);
    buildSurface(16, 12, part, material, [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float longitude   = around * 2.f * (float)M_PI;
      const float latitude    = along * (float)M_PI;
      const float towardEnd   = std::cos(latitude); // > 0 : moitié côté `end`, < 0 : moitié côté `start`
      normal   = tangent * (std::sin(latitude) * std::cos(longitude)) + axis * towardEnd +
                 bitangent * (std::sin(latitude) * std::sin(longitude));
      position = (towardEnd >= -1e-4f ? end : start) + normal * radius;
    });
  }

  // Cube aux arêtes vives (le petit cube de l'antenne du drone). halfSize = demi-côté
  void buildCube(simd::float3 center, float halfSize, uint32_t part, uint32_t material)
  {
    for (int axis = 0; axis < 3; ++axis)
      for (float side : { -1.f, 1.f })
      { // Une face : sa normale, et les deux directions qui la parcourent
        simd::float3 normal = 0.f, tangent = 0.f, bitangent = 0.f;
        normal[axis]              = side;
        tangent[(axis + 1) % 3]   = 1.f;
        bitangent[(axis + 2) % 3] = 1.f;
        const auto firstVertex = (uint32_t)vertices.size();
        for (simd::float2 corner : { simd::float2{ -1, -1 }, simd::float2{ 1, -1 }, simd::float2{ 1, 1 }, simd::float2{ -1, 1 } })
        {
          MeshBuilderVertex vertex{};
          vertex.position = center + (normal + tangent * corner.x + bitangent * corner.y) * halfSize;
          vertex.normal   = normal;
          vertex.part     = part;
          vertex.material = material;
          vertices.push_back(vertex);
        }
        buildTriangle(firstVertex, firstVertex + 1, firstVertex + 2);
        buildTriangle(firstVertex, firstVertex + 2, firstVertex + 3);
      }
  }

  // Cylindre unité (rayon 1, de z = 0 à z = 1), ouvert : à étirer par la matrice de sa pièce (le laser du drone)
  void unitCylinder(uint32_t part, uint32_t material)
  {
    buildSurface(10, 1, part, material, [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float angle = around * 2.f * (float)M_PI;
      normal   = { std::cos(angle), std::sin(angle), 0.f };
      position = { normal.x, normal.y, along }; // along : 0 = base, 1 = bout
    });
  }

  // Tronc de cône de start à end, rayon radiusStart en bas et radiusEnd en haut, ouvert aux deux bouts.
  // radiusEnd = 0 : un cône ; radiusStart = radiusEnd : un cylindre
  void buildFrustum(simd::float3 start, simd::float3 end, float radiusStart, float radiusEnd,
               uint32_t part, uint32_t material, int segmentsAround = 16)
  {
    const simd::float3 axis   = simd::normalize(end - start);
    const float        height = simd::length(end - start);
    simd::float3 tangent, bitangent;
    basisAround(axis, tangent, bitangent);
    // Le flanc va de (radiusStart, 0) à (radiusEnd, height) : sa perpendiculaire vers l'extérieur est
    // (height, radiusStart - radiusEnd) — elle penche vers le haut quand la forme se resserre
    buildSurface(segmentsAround, 1, part, material,
            [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float angle = around * 2.f * (float)M_PI;
      const simd::float3 radial = tangent * std::cos(angle) + bitangent * std::sin(angle);
      const float radius = radiusStart + (radiusEnd - radiusStart) * along; // along : 0 = start, 1 = end
      position = start + axis * (height * along) + radial * radius;
      normal   = simd::normalize(radial * height + axis * (radiusStart - radiusEnd));
    });
  }

  // Disque plein de rayon `radius`, tourné vers `facing` : pour boucher un cylindre ou la base d'un cône
  void buildDisc(simd::float3 center, simd::float3 facing, float radius, uint32_t part, uint32_t material,
            int segmentsAround = 16)
  {
    facing = simd::normalize(facing);
    simd::float3 tangent, bitangent;
    basisAround(facing, tangent, bitangent);
    buildSurface(segmentsAround, 1, part, material,
            [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float angle = around * 2.f * (float)M_PI;
      // along : 0 = centre, 1 = bord
      position = center + (tangent * std::cos(angle) + bitangent * std::sin(angle)) * (radius * along);
      normal   = facing;
    });
  }

  // Cône plein : le flanc, plus un disque qui ferme la base (tourné à l'opposé de la pointe)
  void buildCone(simd::float3 base, simd::float3 tip, float radius, uint32_t part, uint32_t material,
            int segmentsAround = 16)
  {
    buildFrustum(base, tip, radius, 0.f, part, material, segmentsAround);
    buildDisc(base, base - tip, radius, part, material, segmentsAround);
  }

  // Moitié haute d'un ellipsoïde (vers +y), ouverte en bas : une coupole, un cockpit, un abat-jour
  void buildDome(simd::float3 center, simd::float3 radii, uint32_t part, uint32_t material,
            int segmentsAround = 28)
  {
    buildSurface(segmentsAround, segmentsAround / 4, part, material,
            [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float longitude = around * 2.f * (float)M_PI;
      const float latitude  = along * 0.5f * (float)M_PI;   // pôle nord (0) → équateur (π/2)
      const simd::float3 direction = { std::sin(latitude) * std::cos(longitude), std::cos(latitude),
                                             std::sin(latitude) * std::sin(longitude) };
      position = center + direction * radii;
      normal   = simd::normalize(direction / radii);
    });
  }

  // Superellipsoïde : entre la boîte et la sphère. roundness (entre 0.1 et 2) :
  // 1 → ellipsoïde, 0.2 → boîte aux arêtes arrondies, 2 → octaèdre (faces en losange)
  void superEllipsoid(simd::float3 center, simd::float3 radii, float roundness, uint32_t part, uint32_t material,
                      int segmentsAround = 32)
  {
    const float mirror = 2.f - roundness; // la normale suit la puissance « miroir »
    buildSurface(segmentsAround, segmentsAround / 2, part, material,
            [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float longitude = around * 2.f * (float)M_PI;
      const float latitude  = along * (float)M_PI;
      const float ring = std::sin(latitude), height = std::cos(latitude);
      const float cosLon = std::cos(longitude), sinLon = std::sin(longitude);
      // Le même globe que l'ellipsoïde, mais chaque cos / sin passe par une puissance : < 1 gonfle vers la boîte
      position = center + simd::float3{ signedPow(ring, roundness) * signedPow(cosLon, roundness),
                                        signedPow(height, roundness),
                                        signedPow(ring, roundness) * signedPow(sinLon, roundness) } * radii;
      normal   = simd::normalize(simd::float3{ signedPow(ring, mirror) * signedPow(cosLon, mirror),
                                               signedPow(height, mirror),
                                               signedPow(ring, mirror) * signedPow(sinLon, mirror) } / radii);
    });
  }

  // Ressort : un fil qui s'enroule `turns` fois autour de `axis`, de `start` sur `height`.
  // coilRadius = rayon de l'hélice, wireRadius = épaisseur du fil
  void spring(simd::float3 start, simd::float3 axis, float height, float coilRadius, float wireRadius, float turns,
                uint32_t part, uint32_t material)
  {
    axis = simd::normalize(axis);
    simd::float3 tangent, bitangent;
    basisAround(axis, tangent, bitangent);
    const int segmentsAlong = std::max(8, (int)std::ceil(turns * 24.f));   // environ 24 morceaux par tour
    const float climb = coilRadius * turns * 2.f * (float)M_PI;            // longueur d'hélice parcourue à plat
    buildSurface(8, segmentsAlong, part, material, [&](float around, float along, simd::float3& position, simd::float3& normal)
    {
      const float coilAngle = along * turns * 2.f * (float)M_PI;   // où l'on est sur l'hélice
      const float wireAngle = around * 2.f * (float)M_PI;          // où l'on est autour du fil
      const simd::float3 outward  = tangent * std::cos(coilAngle) + bitangent * std::sin(coilAngle);
      const simd::float3 sideways = bitangent * std::cos(coilAngle) - tangent * std::sin(coilAngle);
      // Le fil avance de côté (il tourne) et le long de l'axe (il monte) en même temps
      const simd::float3 wire   = simd::normalize(sideways * climb + axis * height);
      const simd::float3 across = simd::cross(wire, outward);   // perpendiculaire au fil et à `outward`
      normal   = outward * std::cos(wireAngle) + across * std::sin(wireAngle);
      position = start + axis * (height * along) + outward * coilRadius + normal * wireRadius;
    });
  }

    // Tour de potier : fait tourner un profil autour de `axis`. Chaque point du profil = { rayon, hauteur },
    // du bas vers le haut. Un point répété deux fois donne une arête vive au lieu d'un arrondi
    void lathe(simd::float3 base, simd::float3 axis, const std::vector<ProfilePoint>& profile,
               uint32_t part, uint32_t material, int segmentsAround = 24)
    {
        if (profile.size() < 2)
            return;
        axis = simd::normalize(axis);
        simd::float3 tangent, bitangent;
        basisAround(axis, tangent, bitangent);
        const int last = (int)profile.size() - 1;
        buildSurface(segmentsAround, last, part, material, [&](float around, float along, simd::float3& position, simd::float3& normal)
        {
            const int index = (int)std::lround(along * (float)last);   // chaque rangée de la grille = un point du profil
            const ProfilePoint& point = profile[index];
            // Pente du profil autour de ce point (de son voisin du dessous à celui du dessus) ;
            // la normale lui est perpendiculaire : (Δhauteur, -Δrayon)
            const ProfilePoint& below = profile[std::max(index - 1, 0)];
            const ProfilePoint& above = profile[std::min(index + 1, last)];
            const float slopeRadius = above.radius - below.radius;
            const float slopeHeight = above.height - below.height;
            const float angle = around * 2.f * (float)M_PI;
            const simd::float3 radial = tangent * std::cos(angle) + bitangent * std::sin(angle);
            position = base + radial * point.radius + axis * point.height;
            normal   = simd::normalize(radial * slopeHeight - axis * slopeRadius);
        });
    }
};

1. Tisser une surface

Une surface ronde, c'est une fonction : tu lui donnes deux fractions entre 0 et 1, elle te rend un point de la surface et sa normale. buildSurface() l'appelle sur une grille, puis relie les points voisins par des triangles. Toutes les formes rondes passent par là ; chacune ne fournit que sa fonction evaluate.

Passe 1, les sommets. Pour chaque rangée alongIndex et chaque colonne aroundIndex, on demande position et normale. Avec segmentsAround morceaux, il faut segmentsAround + 1 sommets par rangée : le premier et le dernier sont au même endroit (0° et 360°), mais on garde les deux pour que la grille reste un simple rectangle.

Passe 2, les triangles. Chaque case de la grille a quatre coins :

currentnext belowbelowNext around → along ↓
/// C++ — Exemple — les quatre coins d'une case
current   = firstVertex + alongIndex * verticesPerRow + aroundIndex;
next      = current + 1;                // même rangée, colonne suivante
below     = current + verticesPerRow;   // même colonne, rangée suivante
belowNext = below + 1;

buildTriangle(current, next, belowNext);     // le triangle orange
buildTriangle(current, belowNext, below);    // le triangle bleu

Une grille de \( A \times B \) cases donne \( (A + 1)(B + 1) \) sommets et \( 2AB \) triangles. Les sommets sont partagés entre triangles voisins : c'est le gain des indices vu dans ↘ Shapes.

template <class Surface>

evaluate peut être n'importe quelle lambda. Le template fait générer une version de buildSurface() par forme, avec la lambda copiée dedans : aucun appel indirect, aucune allocation, contrairement à un std::function. Surface&& accepte la lambda telle quelle, sans copie.

2. Le bon côté de chaque triangle

Un triangle a deux faces. Metal décide laquelle est devant d'après l'ordre de ses sommets à l'écran. Dès que le culling des faces arrière est actif (setCullMode(MTL::CullModeBack)), un triangle dans le mauvais ordre est éliminé, et ton personnage a des trous.

Plutôt que de raisonner forme par forme, buildTriangle() vérifie lui-même :

  1. faceNormal = produit vectoriel de deux côtés : une flèche perpendiculaire au triangle, dont le sens dépend de l'ordre des sommets.
  2. outward = la somme des normales des trois sommets : le « dehors » voulu.
  3. Si les deux s'opposent (produit scalaire négatif), on échange deux sommets.

Conséquence pratique : une nouvelle forme n'a qu'à donner des normales justes, l'ordre des triangles se règle tout seul. Le test length_squared(faceNormal) < 1e-14f jette les triangles aplatis : aux pôles d'une sphère, à la pointe d'un cône, au centre d'un disque, une rangée entière de sommets tombe sur le même point.

mirrorX est le seul endroit qui doit y penser à la main : un miroir inverse le sens de rotation de tous les triangles, d'où l'échange indices[i + 2] / indices[i + 1] en les recopiant.

3. Les formes

L'ellipsoïde — la base de tout ce qui est rond

Les coordonnées d'un globe : la longitude fait le tour (0 → 2π), la latitude va du pôle nord au pôle sud (0 → π).

\( \vec{d} = \big(\sin(\text{lat})\cos(\text{lon}),\ \cos(\text{lat}),\ \sin(\text{lat})\sin(\text{lon})\big) \qquad \vec{p} = \vec{c} + \vec{d} \odot \vec{r} \)

La normale, elle, se divise par les rayons. L'ellipsoïde est l'ensemble des points où \( \left(\frac{x}{r_x}\right)^2 + \left(\frac{y}{r_y}\right)^2 + \left(\frac{z}{r_z}\right)^2 = 1 \) ; sa normale est le gradient de cette expression, \( \left(\frac{2x}{r_x^2}, \frac{2y}{r_y^2}, \frac{2z}{r_z^2}\right) \), et comme \( x = r_x d_x \), on obtient \( \left(\frac{d_x}{r_x}, \frac{d_y}{r_y}, \frac{d_z}{r_z}\right) \) à un facteur près. D'où normalize(direction / radii).

Le dôme

Le même globe, mais la latitude s'arrête à l'équateur (π/2) : la moitié haute, ouverte en bas. Un cockpit, une coupole, un abat-jour, le haut d'un champignon. Pose un disc dessous pour la fermer.

Le tore

Deux cercles l'un dans l'autre : ringAngle sur le grand anneau, tubeAngle autour du tube. Pour tourner autour de n'importe quel axe, il faut deux directions perpendiculaires à cet axe : c'est le rôle de basisAround, partagé par toutes les formes qui tournent autour d'un axe.

Le piège de basisAround : on obtient ces directions par produit vectoriel avec un vecteur de référence, et si l'axe est presque parallèle à cette référence, le produit tend vers zéro. D'où abs(axis.y) > 0.9f ? kAxisX : kUp.

La capsule

Une sphère coupée à l'équateur dont on écarte les moitiés : cos(latitude) est positif au nord (posé autour de end), négatif au sud (autour de start). Les cases qui enjambent l'équateur s'étirent entre les deux : c'est le cylindre, sans une ligne de plus. La tolérance -1e-4f range la rangée de l'équateur, où \( \cos(\pi/2) \approx -4 \times 10^{-8} \) en flottant, du côté end. Bras, jambes, doigts, cou : la forme la plus utile d'un PNJ.

Le tronc de cône, le cône et le disque

Le flanc va du rayon radiusStart (en bas) au rayon radiusEnd (en haut, à la distance height). Vu de côté, c'est un segment qui va de \( (r_s, 0) \) à \( (r_e, h) \) ; sa direction est \( (r_e - r_s,\ h) \), et une perpendiculaire tournée vers l'extérieur est :

\( \vec{n} = \text{normalize}\big(h \cdot \vec{\text{radial}} + (r_s - r_e) \cdot \vec{\text{axe}}\big) \)

Quand la forme se resserre vers le haut (\( r_s > r_e \)), la normale penche vers le haut ; pour un cylindre (\( r_s = r_e \)) elle est horizontale. Un seul morceau dans le sens de la hauteur suffit : le flanc est droit.

disc est la même grille, mais à plat : along va du centre (rayon 0) au bord. cone n'est rien d'autre qu'un frustum qui finit en pointe, plus un disc tourné à l'opposé de la pointe pour fermer la base. Une forme nouvelle par composition de formes existantes : c'est comme ça que la bibliothèque grandit.

Le superellipsoïde — de la sphère à la boîte

Les personnages stylisés sont rarement des sphères parfaites : un corps en coussin, une tête de robot, une brique aux coins doux. Le superellipsoïde passe de l'un à l'autre avec un seul nombre, roundness :

roundnessforme
0.1 – 0.3boîte aux arêtes arrondies
0.5 – 0.8coussin, galet
1ellipsoïde ordinaire
2octaèdre (faces en losange)

C'est le globe de l'ellipsoïde, mais chaque cosinus et sinus passe par une puissance qui garde son signe (signedPow). Une puissance plus petite que 1 pousse les valeurs vers ±1 : la sphère gonfle vers ses coins. La surface obéit à \( \left|\frac{x}{r_x}\right|^{2/e} + \left|\frac{y}{r_y}\right|^{2/e} + \left|\frac{z}{r_z}\right|^{2/e} = 1 \), et son gradient donne la normale avec la puissance « miroir » \( 2 - e \) — à \( e = 1 \), on retombe exactement sur direction / radii.

Garde roundness entre 0.1 et 2 : au-delà de 2, la puissance miroir devient négative et la normale explose aux pôles.

Le ressort — un tube qui suit une courbe

Antenne en tire-bouchon, queue, cheveux bouclés, ressort de jouet. Le centre du fil suit une hélice : il tourne autour de l'axe en même temps qu'il monte. Autour de ce centre, on trace un petit cercle — mais dans quel plan ?

Il faut un repère qui se déplace avec le fil :

Le petit cercle se trace dans le plan (outward, across), perpendiculaire au fil. C'est la même idée que le tore, mais avec un repère qui change à chaque pas. Pour l'hélice, outward est toujours perpendiculaire au fil ; pour une courbe quelconque ce n'est plus vrai, et il faut un repère plus malin (voir « À toi », plus bas).

Le tour de potier (lathe)

La forme la plus libre : tu donnes un profil — une liste de ProfilePoint { rayon, hauteur } du bas vers le haut — et la bibliothèque le fait tourner autour d'un axe. Un vase, une ampoule, un pion d'échecs, une jupe, un chapeau à large bord, un tronc d'arbre qui s'évase.

Chaque point du profil devient une rangée de la grille. La normale est perpendiculaire à la pente du profil autour de ce point (de son voisin du dessous à son voisin du dessus) : si la pente vaut \( (\Delta r, \Delta h) \), la normale vaut \( (\Delta h, -\Delta r) \) dans le plan (radial, axe).

/// C++ — Exemple — un chapeau à large bord
builder.lathe({ 0.f, 0.7f, 0.f }, { 0.f, 1.f, 0.f },
              { { 0.f,   0.f   },     // le centre, sous le bord
                { 0.30f, 0.f   },     // le bord…
                { 0.30f, 0.f   },     // …répété : arête vive au lieu d'un arrondi
                { 0.30f, 0.02f },
                { 0.14f, 0.03f },     // la calotte
                { 0.12f, 0.20f },
                { 0.f,   0.22f } },   // fermé en haut
              Hat, Cloth);

Un point répété deux fois donne une arête vive : les deux copies prennent chacune la pente d'un seul côté, et la case entre elles, aplatie, est jetée par buildTriangle(). Sans répétition, la normale est moyennée et le coin s'arrondit à l'éclairage. Écris le profil du bas vers le haut : à l'envers, les normales pointeraient vers l'intérieur.

Le cube et le cylindre unité

Le cube ne passe pas par buildSurface() : six faces plates, quatre sommets chacune, donc 24 sommets pour 8 coins. Chaque coin est partagé par trois faces qui regardent dans des directions différentes ; une normale par sommet oblige à le dupliquer, et c'est ce qui garde les arêtes nettes.

Le cylindre unité (rayon 1, de z = 0 à z = 1, ouvert) est fait pour être étiré par la matrice de sa pièce : le laser du drone change de longueur à chaque frame sans qu'on reconstruise rien.

4. Un premier PNJ

Le prochain chapitre construira les vrais PNJ (leur type de sommet, leur animation, leur comportement). Voici déjà à quoi ressemble l'assemblage :

/// C++ — Exemple — un petit PNJ avec la bibliothèque
#include "MeshBuilder.hpp"

enum NpcPart : uint32_t { Body, Head, EyeR, EyeL, ArmR, ArmL, Hat };
enum NpcMaterial : uint32_t { Cloth, Skin, Glass };

MeshBuilder<NpcVertex> buildNpc()
{
    MeshBuilder<NpcVertex> builder;
    builder.superEllipsoid({ 0.f, 0.f, 0.f }, { 0.30f, 0.40f, 0.22f }, 0.6f, Body, Cloth);   // un corps « coussin »
    builder.buildEllipsoid({ 0.f, 0.58f, 0.f }, { 0.20f, 0.20f, 0.20f }, Head, Skin);

    const auto eye = builder.mark();   // tout ce qui suit est construit à droite…
    builder.buildEllipsoid({ 0.07f, 0.62f, 0.17f }, { 0.04f, 0.05f, 0.03f }, EyeR, Glass, 12);
    builder.mirrorX(eye, EyeL);        // …puis reflété à gauche, avec sa propre pièce

    const auto arm = builder.mark();
    builder.buildCapsule({ 0.30f, 0.15f, 0.f }, { 0.42f, -0.20f, 0.05f }, 0.06f, ArmR, Cloth);
    builder.mirrorX(arm, ArmL);

    builder.buildCone({ 0.f, 0.74f, 0.f }, { 0.f, 1.05f, 0.f }, 0.16f, Hat, Cloth);   // le chapeau pointu
    return builder;
}

1 688 sommets, 2 664 triangles, sept pièces animables séparément — et un seul draw call. Les yeux et les bras n'ont été écrits qu'une fois.

Le labo 3D : un mini-Blender pour tes PNJ

Le MeshBuilder ci-dessus, porté ligne pour ligne en JavaScript et rendu en WebGL2 avec l'éclairage de fragment_pnj. Pars d'une page blanche, du mame shiba de Shiba.cpp ou du drone de PNJ.cpp, et construis ton personnage :

  1. Les formes — ajoute-en autant que tu veux, duplique-les, reflète-les (Miroir X : la copie va dans la pièce symétrique, …L ↔ …R). Clique une forme pour la sélectionner, fais-la glisser pour la déplacer dans le plan de l'écran.
  2. Les pièces — chaque forme appartient à une pièce, chaque pièce a son pivot (l'articulation) et son parent. Les pivots sont les points blancs, reliés à leur parent comme les os d'un squelette ; attrape un pivot à la souris pour le placer.
  3. La pose — tourne une pièce autour de son pivot : ses enfants suivent. Si le bras tourne autour du ventre au lieu de l'épaule, le pivot est au mauvais endroit. Balancer anime toutes les poses.
  4. Le code — enums, pivots, buildGeometry() et les matrices de update(), prêts à coller. Ton travail est sauvegardé dans ce navigateur ; Exporter en fait un fichier.
Forme
Pièce
pivot
pose test (degrés)
Matériau
C++ — ton PNJ, prêt à coller

5. Et plus

Combien de triangles ?

FormeGrilleSommetsTriangles
buildEllipsoid (28)28 × 14435728 (784 − 56 aplatis aux pôles)
buildDome (28)28 × 7232364
superEllipsoid (32)32 × 16561960
buildTorus32 × 12429768
buildCapsule16 × 12221352
buildFrustum (16)16 × 13432
buildDisc (16)16 × 13416
buildCone (16)flanc + disque6832
spring (4 tours)8 × 968731 536
buildCube6 faces2412
unitCylinder10 × 12220

Doubler segmentsAround sur une forme ronde multiplie ses triangles par quatre quand l'autre sens suit. Pour une foule de PNJ, c'est le premier réglage à baisser : un PNJ lointain avec 12 segments au lieu de 28 coûte cinq fois moins, et personne ne voit la différence à vingt mètres.

Mesh ou SDF ?

Les mêmes formes existent en distance signée, comme dans ↘ SDF — math :

/// MSL — Exemple — les mêmes formes, en distance
float sdTorus(float3 p, float ringRadius, float tubeRadius)
{
    float2 q = float2(length(p.xz) - ringRadius, p.y);
    return length(q) - tubeRadius;
}

float sdCapsule(float3 p, float3 start, float3 end, float radius)
{
    float3 pa = p - start, ba = end - start;
    float  h  = clamp(dot(pa, ba) / dot(ba, ba), 0.0, 1.0);
    return length(pa - ba * h) - radius;
}

Le mesh est explicite : écrit une fois en triangles, rastérisé très vite, avec la profondeur, les ombres et l'éclairage du pipeline habituel — le bon choix pour des PNJ qui vivent dans une scène en triangles. La SDF est implicite : rien n'est stocké, chaque pixel recalcule sa distance. Parfaite pour des formes qui fusionnent ou se déforment, plus chère dès qu'il faut la mêler au reste.

Les normales sous une échelle

Le direction / radii de l'ellipsoïde est un cas particulier d'une règle générale : quand une matrice \( M \) déforme un objet, ses normales se transforment avec \( (M^{-1})^{T} \), pas avec \( M \). Pour une échelle \( \text{diag}(r_x, r_y, r_z) \), l'inverse transposée vaut \( \text{diag}(1/r_x, 1/r_y, 1/r_z) \). Le jour où une pièce de PNJ s'étire dans le shader (un personnage qui s'écrase en sautant), c'est cette matrice-là qu'il faudra appliquer à ses normales.

À toi :

1. Un tube(points, radius) qui suit n'importe quelle courbe (une queue, un cordon, une branche). Le piège : outward n'est plus forcément perpendiculaire au fil. Commence avec une direction perpendiculaire à la première tangente, puis, à chaque point, retire-lui sa composante le long de la nouvelle tangente et renormalise (\( \vec{o} \leftarrow \text{normalize}(\vec{o} - (\vec{o}\cdot\vec{t})\,\vec{t}) \)) : c'est le transport parallèle, et le tube ne se vrille plus.

2. Un PNJ de ton invention avec au moins un lathe, un superEllipsoid et un mirrorX.