Chapitre 13 · Viewport & Scissor

Le Viewport — définir la zone de rendu et la passer au shader

Avant de dessiner quoi que ce soit, le GPU a besoin de savoir où il dessine sur la surface. C'est le rôle du MTLViewport : transformer les coordonnées Normalized Device Coordinates, de -1 à +1 en coordonnées pixels réelles sur ton drawable. Sans viewport explicite, Metal en applique un par défaut — ce qui fonctionne, mais dès que tu veux plusieurs vues, du letterboxing, ou passer la résolution à un shader, tu dois le contrôler toi-même.

Objectif de ce chapitreWhat you’ll learn
Wat je leert
  • Connaitre les coordonnées et conventions Metal
⏱ ~25 min

Viewport coordinate system on Metal

+X +Y (0, 0) originXY (WIDTH, 0) (0, HEIGHT) (W, H) (W/2, H/2)

La structure MTL::Viewport en C++

Le viewport est une simple structure dans metal-cpp — pas d'allocation, pas de release — c'est une valeur (comme double, float, NS::UInteger, …). Pas un objet Metal.

/// C++ — Exemple — défini dans Metal/MTLRenderCommandEncoder.hpp
struct Viewport
{
    double originX;   // coin haut-gauche en pixels
    double originY;   // idem
    double width;     // largeur en pixels
    double height;    // hauteur en pixels
    double znear;     // profondeur minimale [0.0 … 1.0]
    double zfar;      // profondeur maximale [0.0 … 1.0]
};

Normalized device coordinate system (NDC) on Metal

left-handed coordinate system +X +Y +Z (0,0,0) (0,0,1) (-1,-1,0) (1,-1,0) (1,1,0) (-1,1,0) (-1,-1,1) (1,-1,1) (1,1,1) (-1,1,1)
NDC → pixels

En NDC, le centre de l'écran est (0,0). Les bords vont de -1 à +1 sur X et Y.

En NDC également, Y monte. — comme en maths.

En pixels/viewport, Y descend. — convention écran standard — comme une image.

Le viewport fait la conversion entre les deux automatiquement. Tu n'as rien à inverser dans ton shader.

Petite parenthèse : Normalized 2D texture coordinate system (UV) on Metal

+U +V (0, 0) (1, 0) (0, 1) (1, 1) (0.5, 0.5)

Stocker et mettre à jour le viewport

Dans le chapitre précédent se trouvait la fonction à implémenter obligatoirement drawableSizeWillChange() du protocole MTKViewDelegate.

Celle-ci prévient notre MTKView (vue) lorsque la fenêtre d'application change de taille. Tu en auras souvent besoin, nous créons un pont Obj-C++ ←→ C++

Exemple sur MacBook 14 pouces

L'écran fait 3024 × 1964 pixels, soit 5 939 136 pixels. Fenêtre agrandie au maximum, la fonction reçoit un CGSize (deux CGFloat, des double sur Mac) de 3024 × 1898 : le drawable de la MTKView compte donc 5 739 552 pixels. Les 66 lignes du haut (66 × 3024 = 199 584 pixels) restent hors de la surface de rendu. Un viewport plus grand que le drawable tronque l'affichage.

/// Objective-C++ — AppViewController.mm — update:18/05/26
- (void)mtkView:(MTKView *)view drawableSizeWillChange:(CGSize)size
{
  NSLog(@"drawable size: %.0f x %.0f", size.width, size.height); // print tes valeurs dans la console
  m_renderer->resizeViewWindow((NS::UInteger)size.width, (NS::UInteger)size.height);
}
⬡CheckPoint Compilation — regarde dans la console

Nous avons construit une fonction afin de remplir les données de notre viewport qui est appelé à chaque resize via resizeViewWindow(), notre équivalence C++ de la fonction drawableSizeWillChange().

On donne les valeurs de droite à gauche.

/// C++ — Renderer.cpp — update:18/05/26
void Renderer::updateViewportWindow(NS::UInteger width, NS::UInteger height)
{
  m_viewport.originX = 0.0;
  m_viewport.originY = 0.0;
  m_viewport.width   = (double)width; // transforme l'UInteger en double avant l'attribution (cast)
  m_viewport.height  = (double)height;
  m_viewport.znear   = 0.0;   // toujours 0.0 sauf cas spéciaux
  m_viewport.zfar    = 1.0;   // toujours 1.0 sauf cas spéciaux
}
important

znear et zfar ne sont pas les plans near/far de ta caméra — ce sont les bornes de remapping de la valeur de profondeur dans le depth buffer. En Metal, la convention est [0.0, 1.0]. Ne change pas ces valeurs sauf si tu fais du reverse-Z intentionnel.

/// C++ — Renderer.hpp — update:18/05/26
private:
    void updateViewportWindow(NS::UInteger width, NS::UInteger height); // Prototype de notre fonction
    void update(const FrameTime& time);
    MTL::PixelFormat            m_depthPixelFormat;
    MTL::Viewport               m_viewport; // Une copie de la structure, membre de la classe
/// C++ — Renderer.cpp — update:18/05/26
void Renderer::resizeViewWindow(NS::UInteger width, NS::UInteger height)
{
  updateViewportWindow(width, height); // Mise à jour des valeurs quand la fenêtre change
}

Lorsque la fenêtre est créé, drawableSizeWillChange() n'est pas appelé, on doit aussi appeler notre fonction dans le constructeur de notre classe principale par exemple :

/// C++ — Renderer.cpp — update:18/05/26
{
  resizeViewWindow(width, height);
}

Appliquer le viewport dans ta fonction de dessin, ici draw()

Le viewport est appliqué sur le MTL::RenderCommandEncoder, une fois par pass, avant tout draw call :

/// C++ — Exemple — update:18/05/26
void Renderer::draw(MTK::View* view, double timeStamp, float delta)
{
  NS::AutoreleasePool* autoreleasePool = NS::AutoreleasePool::alloc()->init();

  MTL::CommandBuffer* commandBuffer = m_commandQueue->commandBuffer();
  MTL::RenderPassDescriptor* renderPassDescriptor  = view->currentRenderPassDescriptor();
  MTL::RenderCommandEncoder* renderCommandEncoder = commandBuffer->renderCommandEncoder(renderPassDescriptor);

  renderCommandEncoder->setViewport(m_viewport);
  // some code …
  renderCommandEncoder->setViewport(m_viewport); // si nécessaire
  // same …

  renderCommandEncoder->endEncoding();
  commandBuffer->presentDrawable(view->currentDrawable());
  commandBuffer->commit();

  autoreleasePool->release();
}

Passer la résolution au shader

Le viewport est un état CPU — le shader n'y a pas accès directement. Pour passer la résolution (utile pour les effets plein-écran, le SDF (texte), le ray marching, les coordonnées UV comme la texture de profondeur), tu peux créer une structure de données et tu la passes au shader via un buffer, une table d'argument (Metal 4) ou juste une donnée sans buffer.

1. Déclarer la donnée

/// C++ — Renderer.hpp — update:18/05/26
private:
  simd::float2 m_windowSize; // après les membres MTL

1. Déclarer la structure partagée

Dans un header partagé entre C++ & MSL :

/// C++ — Renderer_shared.h — update:18/05/26 — partagé CPU & GPU
#ifndef Renderer_shared_h
#define Renderer_shared_h

#include <simd/simd.h>

struct WindowUniforms
{
  simd::float2 windowSize;
};

#endif /* Renderer_shared_h */
Alignement

simd::float2 est aligné sur 8 bytes côté CPU et float2 sur 8 bytes côté GPU. La structure est identique des deux côtés — c'est pour ça qu'on utilise simd:: plutôt que deux float séparés.

Créer le buffer côté C++ pour la structure uniquement

/// C++ — Renderer.hpp — update:18/05/26 — membre (m_) de la classe, (initialisation = une fois)
#include "../includes/SharedGPU/Renderer_shared.h"
// membre de la classe principale
private:
  NS::SharedPtr<MTL::Buffer> m_windowSizeBuffer;
  WindowUniforms             m_windowUniforms;
/// C++ — Renderer.cpp — update:18/05/26 — dans le constructeur (allocation = une fois)
{
  m_windowSizeBuffer = NS::TransferPtr(m_device->newBuffer(sizeof(WindowUniforms), MTL::ResourceStorageModeShared));
}

2. Remplir les données de largeur et de hauteur à jour

/// C++ — Renderer.cpp — update:18/05/26
void Renderer::resizeViewWindow(NS::UInteger width, NS::UInteger height)
{
  // La donnée :
  m_windowSize.x = (float)width;
  m_windowSize.y = (float)height;
  //                         x             y
  m_windowSize = { (float)width, (float)height }; // OU en une ligne

  // La structure :
  m_windowUniforms.windowSize.x = (float)width;
  m_windowUniforms.windowSize.y = (float)height;
  memcpy(m_windowSizeBuffer->contents(), &m_windowUniforms, sizeof(WindowUniforms));

  updateViewportWindow(width, height);
} // On pourrait très bien effectuer cette action dans notre fonction updateViewportWindow()..

3. Recevoir la donnée dans le shader MSL (sans MTLBuffer)

/// C++ — Renderer.cpp — update:18/05/26
MTL::RenderCommandEncoder* renderCommandEncoder = commandBuffer->renderCommandEncoder(renderPassDescriptor);

renderCommandEncoder->setViewport(m_viewport);
renderCommandEncoder->setRenderPipelineState(m_renderPipelineState.get());

renderCommandEncoder->setFragmentBytes(&m_windowSize, sizeof(m_windowSize), 1);
renderCommandEncoder->drawPrimitives(MTL::PrimitiveTypeTriangle, NS::UInteger(0), NS::UInteger(3));
renderCommandEncoder->endEncoding();
setFragmentBytes

Pourquoi il n'y a pas de buffer dans ce cas ? Metal en crée un temporaire pour nous… La méthode d'instance setFragmentBytes:length:atIndex: crée un tampon à partir d'octets et l'attribue à une entrée dans la table d'arguments du shader de fragments.

Important : Appelez cette méthode uniquement pour les données à usage unique inférieures à 4 Ko (4096 octets - 8 octets, on est large)

/// MSL — Radial.metal — update:13/10/26
#include <metal_stdlib>
#include "../includes/SharedGPU/Renderer_shared.h"
using namespace metal;

struct VertexOut
{
    float4 position [[position]]; // pas besoin d'écriture du namespace simd:: dans les fichiers metal
    float2 uv;
};

// vertex_id : index automatique du sommet (0, 1, 2) par Metal
vertex VertexOut vertex_main_radial(uint vid [[vertex_id]])
{
  // Trois sommets en NDC — x ∈ [-1, 1], y ∈ [-1, 1] (appartient à)
  // Centre de la fenêtre = (0, 0)
  constexpr float2 positions[3] = {
      { -1.0,  3.0 },   // Top-Left
      {  3.0, -1.0 },   // Bottom-Right
      { -1.0, -1.0 },   // Bottom-Left
  };

  VertexOut out;
  out.position = float4(positions[vid], 0.5, 1.0); // 3D + w
  out.uv       = (positions[vid] + 1.0) * 0.5;     // [0, 1], 0,5 = centre pixel
  return out;
}

fragment float4 fragment_main_radial(VertexOut        in         [[stage_in]],
                                     constant float2& windowSize [[buffer(1)]])
{
  float2 uv     = in.uv; // coordonnée dans la texture (surface plane)
  float  aspect = windowSize.x / windowSize.y; // ~1.6, ~1.8 pour une fenêtre rectangulaire
  float2 st     = (uv - 0.5) * float2(aspect, 1.0); // centré, ratio correct (1/2 pixel)

  // dégradé radial au centre
  float r = length(st);
  float c = smoothstep(0.5, 0.0, r);
  return float4(c, c * 0.4, 1.0 - c, 1.0);
}

3. Recevoir le buffer dans le shader MSL (struct)

/// C++ — Renderer.cpp — update:18/05/26 — dans draw(), avant les draw calls
renderCommandEncoder->setViewport(m_viewport);
renderCommandEncoder->setRenderPipelineState(m_renderPipelineState.get());

renderCommandEncoder->setVertexBuffer(m_windowSizeBuffer.get(), 0, 1);      // slot 1, uniforms
renderCommandEncoder->setFragmentBuffer(m_windowSizeBuffer.get(), 0, 1);    // même buffer, même slot
/// MSL — FullScreen.metal — update:18/05/26 — d'abord un triangle prenant la ~moitié de l'écran
#include <metal_stdlib> // Toujours inclure

#include "../includes/SharedGPU/Renderer_shared.h"

using namespace metal; // Toujours inclure

struct VertexOut
{
  float4 position [[position]];
};

vertex VertexOut vertex_main(uint                     vid      [[vertex_id]],
                             constant WindowUniforms& uniforms [[buffer(1)]])
{
  constexpr float2 positions[3] = {
    { -1.0,  1.0 },
    {  1.0, -1.0 },
    { -1.0, -1.0 },
  };
  VertexOut out;
  out.position = float4(positions[vid], 0.0, 1.0);
  return out;
}

fragment float4 fragment_main(VertexOut in [[stage_in]])
{
  return float4(0.4, 1.0, 1.0, 1.0);
}

Un shader est un programme qui tourne sur le GPU. Le fichier a l'extension .metal et contient du MSL — Metal Shading Language, un dialecte de C++14.

Triangle plein-écran

Un seul triangle de 3 sommets avec des positions exagérées (-1, 3 et 3, -1) couvre l'intégralité du viewport après clipping. C'est plus efficace qu'un quad (2 triangles) et évite un artefact sur la diagonale. Technique standard dans les moteurs AAA.

Tu peux essayer les 2 shaders mais tu dois changer les noms des fonctions MSL dans buildPipeline(). (Le rendu sera identique excepté le dégradé radial).

Aperçu Metal 4

/// MSL — Exemple — update:18/05/26 — Metal 4 — ArgumentTable Alloc/Init
{
  auto _residencySetDescriptor = NS::TransferPtr(MTL::ResidencySetDescriptor::alloc()->init());
  _residencySetDescriptor->setLabel(MTLSTR("ResidencySetDescriptor")); // Facultatif

  NS::Error* error = nullptr;
  MTL::ResidencySet* _residencySet = device->newResidencySet(_residencySetDescriptor.get(), &error);

  _residencySet->requestResidency(); // MTL::ResidencySet* ; serait en membre de l'objet.
  _residencySet->addAllocation(m_windowSizeBuffer.get());
  _residencySet->commit();
  m_commandQueue->addResidencySet(_residencySet);
}

auto remplace ici NS::SharedPtr<MTL::ResidencySetDescriptor>.

/// MSL — Exemple — update:18/05/26 — Metal 4 — ArgumentTable
MTL4::ArgumentTable* _argumentTable->setAddress(m_windowSizeBuffer->gpuAddress(), 1);
ArgumentTable

Fournit un mécanisme pour gérer et fournir des liaisons de ressources pour les tampons, les textures, les états de l'échantillonneur et d'autres ressources Metal. C'est plus optimisé. On y reviendra dans les prochains chapitres.

Le pipeline de rendu

Un pipeline de rendu Metal se configure une seule fois, avant de dessiner : il désigne les shaders de sommets et de fragments, et fixe la façon dont le GPU traite la géométrie. Le MTLRenderPipelineDescriptor en est le plan : on le remplit, on le compile en MTL::RenderPipelineState, puis chaque frame réutilise cet objet sans recompilation.

Les shaders MSL échangent leurs données avec le programme C++ via des tampons mémoire (buffers), lisibles et modifiables par le CPU.

Déclaration — notre configuration

/// C++ — Renderer.hpp — update:18/05/26
private:
  void buildPipeline();
  // …
  NS::SharedPtr<MTL::RenderPipelineState> m_renderPipelineState;
  1. buildPipeline() → Notre fonction qui sera appelée une seule fois, afin de compiler les fonctions de shaders écrites en MSL.
  2. MTLRenderPipelineState → L'objet Metal qui reçoit les règles de rendu déjà compilé.
/// C++ — Renderer.cpp — update:18/05/26
void Renderer::buildPipeline()
{
  auto vertexFunction = NS::TransferPtr(m_shaderLibrary->newFunction(MTLSTR("vertex_main")));
  auto fragmentFunction = NS::TransferPtr(m_shaderLibrary->newFunction(MTLSTR("fragment_main")));
  auto renderPipelineDescriptor = NS::TransferPtr(MTL::RenderPipelineDescriptor::alloc()->init());
  renderPipelineDescriptor->setVertexFunction(vertexFunction.get());
  renderPipelineDescriptor->setFragmentFunction(fragmentFunction.get());
  // Format de pixels qui doivent correspondrent à MTKView
  renderPipelineDescriptor->colorAttachments()->object(0)->setPixelFormat(m_pixelFormat);
  renderPipelineDescriptor->setDepthAttachmentPixelFormat(m_depthPixelFormat);
  // Gestion erreur potentielle "error->localizedDescription()" contient le message d'erreur
  NS::Error* error = nullptr;
  m_renderPipelineState  = NS::TransferPtr(m_device->newRenderPipelineState(renderPipelineDescriptor.get(), &error));
  assert(!error && "Pipeline creation failed");
}
  1. vertex_main → Notre future fonction MSL qui est compilée via la méthode newFunction() appartenant à la classe MTLLibrary.
  2. 1er & 2e auto → Remplace MTL::Function* ou NS::SharedPtr<MTL::Function> dans le cas d'utilisation des pointeurs intelligents depuis C++17. La valeur remplacée est la valeur renvoyée par la méthode qui compile les fonctions de shaders.
  3. 3e auto → Remplace NS::SharedPtr<MTL::RenderPipelineDescriptor>.
  4. get() → Récupère le pointeur intelligent qui libère sa mémoire automatiquement.
  5. setDepthAttachmentPixelFormat() → N'est nécessaire que lorsque l'on déclare un format de pixel du type pour notre drawable (pour les projets avancés).
  6. m_device->newRenderPipelineState() → Le protocole GPU utilise sa méthode/fonctionnalité pour que les données soient prêtes à être ajoutées en file d'attente pour le rendu.
Compiler une seule fois
La compilation du PSO est coûteuse (200–500ms parfois). Elle compile les shaders vers du bytecode GPU natif. On la fait au démarrage, jamais dans la boucle de rendu.
/// C++ — Renderer.cpp — update:18/05/26 — dans le constructeur (allocation = une fois) — après le buffer
{
  buildPipeline();
}
⬡CheckPoint Compilation — notre triangle est clairement visible

Les étapes que tu configures avant de dessiner le rendu 3D :

Données 3D (vertices)
        │
        ▼
┌────────────────┐
│  Vertex Stage  │  ← ton vertex shader (MSL) : transforme chaque sommet
└───────┬────────┘
        │  positions en clip space
        ▼
┌────────────────┐
│ Rasterization  │  ← GPU automatique : convertit triangles → fragments (pixels)
└───────┬────────┘
        │  fragments (pixels potentiels)
        ▼
┌────────────────┐
│ Fragment Stage │  ← ton fragment shader (MSL) : calcule la couleur finale de chaque pixel
└───────┬────────┘
        │
        ▼
Framebuffer (image finale à l'écran)
BL BR TL [0, 0] centre de la fenêtre BL BR TL rastérisation BL BR TL fragment stage

En blanc, la partie de pixels à utiliser.

En bleu, notre fragment shader. Sur un vrai écran, la rastérisation est bien plus fine que sur ce schéma.

Ce que Metal ajoute : le TBDR

Sur Apple Silicon, la rastérisation différée par tuile signifie que le GPU découpe le framebuffer en tuiles (typiquement 32×32 pixels), résout la visibilité (hidden surface removal) avant d'exécuter les fragment shaders. Résultat : les fragments cachés ne coûtent rien en compute.

Conséquence pratique
Sur Apple Silicon, le Z-test (depth) est fait avant le fragment shader, pas après. L'overdraw coûte moins cher qu'ailleurs. C'est pour ça que les iPhones rendent des scènes complexes sans chauffer.
/// MSL — FullScreen.metal — update:18/05/26
vertex VertexOut vertex_main(uint                     vid      [[vertex_id]],
                             constant WindowUniforms& uniforms [[buffer(1)]])
{
    // triangle plein-écran sans vertex buffer (3 sommets suffisent)
    constexpr float2 positions[3] = {
        { -1.0,  3.0 },
        {  3.0, -1.0 },
        { -1.0, -1.0 },
    };
    VertexOut out;
    out.position = float4(positions[vid], 0.0, 1.0);
    return out;
}
⬡CheckPoint Compilation — notre triangle prend toute la surface de la fenêtre

Une version plus optimisée qui donne le même résultat

/// MSL — FullScreen.metal — update:13/10/26
vertex VertexOut vertex_main(uint                     vid      [[vertex_id]],
                             constant WindowUniforms& uniforms [[buffer(1)]])
{ // Top-Left (-1, 3) > Bottom-Right (3, -1) > Bottom-Left (-1, -1)
  float2 positions = float2(vid & 1, vid == 0) * 4.0f - 1.0f;

  VertexOut out;
  out.position = float4(positions, 0.0, 1.0); // retire [vid]
  return out;
}

GPU vs CPU

Le GPU n'est pas un CPU plus rapide — c'est une machine fondamentalement différente, conçue autour d'une idée unique : faire la même chose sur des milliers de données en même temps.

Un CPU est conçu pour le débit séquentiel : peu de cœurs (4-32), très rapides, avec des caches énormes et une logique de prédiction de branchement sophistiquée. Il excelle à exécuter du code complexe, avec beaucoup de conditions, de dépendances, de sauts.

Un GPU est l'inverse : des milliers de cœurs simples, moins rapides individuellement, mais capables d'exécuter le même programme sur des milliers d'éléments simultanément. C'est du SIMD — Single Instruction, Multiple Data.

Analogie
CPU = un chirurgien expert. GPU = 4000 ouvriers qui peignent chacun un pixel en même temps. Pour peindre un mur, l'usine gagne. Pour opérer un patient, le chirurgien est indispensable.
Téraflop (ou TFLOP)

Unité de mesure qui indique la puissance de calcul d'un processeur (CPU ou GPU). Il représente mille milliards (1 000 000 000 000) d'opérations en virgule flottante (calculs avec des nombres à virgule) par seconde

La puce M2 Pro offre une puissance de calcul graphique allant jusqu'à 5,7 TFLOPS pour la déclinaison d'entrée de gamme à 16 cœurs.

/// C++ — Renderer.cpp — update:18/05/26 — remplaces les noms des fonctions MSL
void Renderer::buildPipeline()
{
  auto vertexFunction = NS::TransferPtr(m_shaderLibrary->newFunction(MTLSTR("vertex_main_radial")));
  auto fragmentFunction = NS::TransferPtr(m_shaderLibrary->newFunction(MTLSTR("fragment_main_radial")));
  auto renderPipelineDescriptor = NS::TransferPtr(MTL::RenderPipelineDescriptor::alloc()->init());
  renderPipelineDescriptor->setVertexFunction(vertexFunction.get());
  renderPipelineDescriptor->setFragmentFunction(fragmentFunction.get());
  renderPipelineDescriptor->colorAttachments()->object(0)->setPixelFormat(m_pixelFormat);
  renderPipelineDescriptor->setDepthAttachmentPixelFormat(m_depthPixelFormat);
  NS::Error* error = nullptr;
  m_renderPipelineState  = NS::TransferPtr(m_device->newRenderPipelineState(renderPipelineDescriptor.get(), &error));
  assert(!error && "Pipeline creation failed");
}
⬡CheckPoint Compilation — dégradé radial au centre

Le Scissor — zone de rendu stricte

Le scissor est un rectangle en pixels qui coupe net tout ce qui est en dehors — là où le viewport transforme, le scissor coupe. Optionnel, mais utile pour les UIs, les shadow maps, le rendu partiel :

MTL::ScissorRect scissor;
scissor.x      = 0; // Les 4 données de la structure Metal sont des NS::UInteger, pas de cast nécessaire
scissor.y      = 0;
scissor.width  = m_width;
scissor.height = m_height;

renderCommandEncoder->setScissorRect(scissor);   // après setViewport()
Ordre

Toujours dans cet ordre : setViewport → setScissorRect → setRenderPipelineState → draw calls. Changer le viewport ou le scissor après un draw call l'applique aux draws suivants seulement.

Points clés à retenir ;

  1. buffer(1) → l'index de slot du buffer. Le slot 0 est souvent réservé au vertex buffer. On commence les uniforms au slot 1 par convention.
  2. Triangle plein-écran → 3 sommets, 0 vertex buffer, 1 draw call. Pattern standard pour les passes de post-processing et les shaders procéduraux.
  3. ScissorRect → coordonnées en pixels entiers (NS::UInteger), doit rester dans les bornes du drawable — sinon validation error au runtime.