# Capitolo 3: OpenGL - La Tecnologia di Rendering

## Cos'è OpenGL?

**OpenGL** (Open Graphics Library) è uno standard aperto per il rendering di grafica 2D e 3D. È come un "linguaggio universale" che permette al tuo programma di comunicare con la scheda grafica (GPU).

### Analogia Semplice

Immagina OpenGL come un **interprete** tra te e un artista professionista (la GPU):

```
Tu: "Voglio un cubo rosso"
    ↓
OpenGL: Traduce in comandi GPU
    ↓
GPU: Disegna il cubo
    ↓
Schermo: Vedi il risultato
```

## Perché OpenGL?

### Vantaggi

✅ **Cross-platform**: Funziona su Windows, Mac, Linux
✅ **Standard aperto**: Gratis e open source
✅ **Accelerazione hardware**: Usa la potenza della GPU
✅ **Maturo e stabile**: In uso da decenni
✅ **Ben documentato**: Tantissime risorse e tutorial

### Alternative

- **DirectX**: Solo Windows (usato nei giochi AAA)
- **Vulkan**: Moderno ma complesso
- **Metal**: Solo Apple
- **WebGL**: OpenGL per browser

Per progetti educativi e multi-piattaforma, OpenGL è perfetto!

## Come Funziona OpenGL

### Macchina a Stati

OpenGL è una **state machine** (macchina a stati). Una volta impostata, mantiene le configurazioni:

```python
# Imposta uno stato
glEnable(GL_DEPTH_TEST)      # Attiva depth buffer
glLineWidth(5.0)             # Linee spesse 5 pixel

# Tutti i disegni successivi useranno questi stati!
draw_something()
draw_something_else()

# Cambia stato
glDisable(GL_DEPTH_TEST)     # Disattiva depth buffer
glLineWidth(1.0)             # Linee sottili
```

### Contesto OpenGL

Prima di usare OpenGL, devi creare un **contesto**:

```python
import pygame
from pygame.locals import DOUBLEBUF, OPENGL

# Crea finestra con contesto OpenGL
pygame.display.set_mode((800, 600), DOUBLEBUF | OPENGL)
```

Il contesto è l'ambiente in cui OpenGL opera.

## Pipeline di Rendering

OpenGL processa la geometria attraverso una pipeline:

```
1. VERTICI                    2. ASSEMBLAGGIO
   ↓                             ↓
   Punti 3D                      Forme geometriche
   (x, y, z)                     (triangoli, quad)
   
3. TRASFORMAZIONI              4. RASTERIZZAZIONE
   ↓                             ↓
   Applica matrici               Converte in pixel
   (model, view, projection)     
   
5. FRAGMENT SHADER             6. TEST & BLENDING
   ↓                             ↓
   Colora ogni pixel             Depth test, trasparenza
   
7. FRAMEBUFFER
   ↓
   Immagine finale sullo schermo
```

### Spiegazione Passo per Passo

**1. Vertici**
```python
# Definisci un quadrato
v1 = (0, 0, 0)
v2 = (1, 0, 0)
v3 = (1, 1, 0)
v4 = (0, 1, 0)
```

**2. Assemblaggio**
```python
glBegin(GL_QUADS)  # Inizia un quadrilatero
    glVertex3f(0, 0, 0)  # v1
    glVertex3f(1, 0, 0)  # v2
    glVertex3f(1, 1, 0)  # v3
    glVertex3f(0, 1, 0)  # v4
glEnd()
```

**3. Trasformazioni**
```python
# Model: posiziona oggetto
glTranslatef(x, y, z)

# View: posiziona camera
gluLookAt(eye_x, eye_y, eye_z,
          center_x, center_y, center_z,
          up_x, up_y, up_z)

# Projection: crea prospettiva
gluPerspective(fov, aspect, near, far)
```

**4-7**: OpenGL gestisce automaticamente!

## Primitive Geometriche

OpenGL può disegnare varie forme base:

### Punti
```python
glBegin(GL_POINTS)
    glVertex3f(0, 0, 0)
    glVertex3f(1, 1, 0)
glEnd()

Risultato:  • •
```

### Linee
```python
glBegin(GL_LINES)
    glVertex3f(0, 0, 0)  # Punto 1 linea A
    glVertex3f(1, 0, 0)  # Punto 2 linea A
    glVertex3f(1, 0, 0)  # Punto 1 linea B
    glVertex3f(1, 1, 0)  # Punto 2 linea B
glEnd()

Risultato:  ●──●
             │
             │
             ●
```

### Triangoli
```python
glBegin(GL_TRIANGLES)
    glVertex3f(0, 0, 0)
    glVertex3f(1, 0, 0)
    glVertex3f(0.5, 1, 0)
glEnd()

Risultato:    ●
             ╱ ╲
            ╱   ╲
           ●─────●
```

### Quadrilateri (Quads) - Quello che usiamo!
```python
glBegin(GL_QUADS)
    glVertex3f(0, 0, 0)
    glVertex3f(1, 0, 0)
    glVertex3f(1, 1, 0)
    glVertex3f(0, 1, 0)
glEnd()

Risultato:  ●─────●
            │     │
            │     │
            ●─────●
```

## Matrici di Trasformazione

### Due Modalità

OpenGL ha due tipi di matrici:

```python
GL_PROJECTION  # Per la proiezione (prospettiva/ortogonale)
GL_MODELVIEW   # Per modello e vista (oggetti e camera)
```

### Workflow Tipico

```python
# 1. Setup proiezione
glMatrixMode(GL_PROJECTION)
glLoadIdentity()  # Resetta matrice
gluPerspective(45, aspect_ratio, 0.1, 1000.0)

# 2. Setup vista e modello
glMatrixMode(GL_MODELVIEW)
glLoadIdentity()  # Resetta matrice

# 3. Posiziona camera
gluLookAt(cam_x, cam_y, cam_z,  # Posizione camera
          0, 0, 0,               # Guarda verso l'origine
          0, 1, 0)               # Vettore "su"

# 4. Disegna oggetti
draw_terrain()
```

## Illuminazione in OpenGL

### Setup Base

```python
# Abilita illuminazione
glEnable(GL_LIGHTING)
glEnable(GL_LIGHT0)  # Attiva la prima luce

# Colori materiale dai vertici
glEnable(GL_COLOR_MATERIAL)
glColorMaterial(GL_FRONT_AND_BACK, GL_AMBIENT_AND_DIFFUSE)
```

### Configurare la Luce

```python
# Posizione luce (x, y, z, w)
# w=0 → luce direzionale (come il sole)
# w=1 → luce posizionale (come una lampada)
glLightfv(GL_LIGHT0, GL_POSITION, [1.0, 1.0, 1.0, 0.0])

# Luce ambientale (illuminazione generale)
glLightfv(GL_LIGHT0, GL_AMBIENT, [0.4, 0.4, 0.4, 1.0])

# Luce diffusa (illuminazione direzionale)
glLightfv(GL_LIGHT0, GL_DIFFUSE, [0.8, 0.8, 0.8, 1.0])
```

### Effetto dell'Illuminazione

```
Senza illuminazione:          Con illuminazione:
┌────┐ ┌────┐                 ┌────┐ ┌────┐
│    │ │    │                 │▓▓▓▓│ │░░░░│ ← Lati con
│    │ │    │                 │▓▓▓▓│ │░░░░│   ombreggiature
└────┘ └────┘                 └────┘ └────┘   diverse
 Tutto                         Profondità
 uguale                        visibile
```

## Depth Testing (Test di Profondità)

### Il Problema

Senza depth testing, gli oggetti si sovrappongono male:

```
Disegnato prima:  A        Disegnato dopo: B
┌───────┐                     ┌───────┐
│   A   │                     │   B   │
│       │     +               │       │ = ┌───────┐
└───────┘       ┌───────┐     └───────┘   │   B   │  ← B copre A
                │   B   │                  │       │    anche se è
                └───────┘                  └───────┘    dietro!
```

### La Soluzione

```python
glEnable(GL_DEPTH_TEST)  # Abilita depth buffer

# Ogni frame:
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
```

Ora OpenGL disegna correttamente tenendo conto della profondità!

## Blending (Trasparenza)

Per oggetti semi-trasparenti:

```python
glEnable(GL_BLEND)
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)

# Ora puoi usare colori con trasparenza
glColor4f(1.0, 0.0, 0.0, 0.5)  # Rosso al 50%
```

## Comandi OpenGL Usati nel Progetto

### Inizializzazione

```python
# Abilita test profondità
glEnable(GL_DEPTH_TEST)

# Abilita blending per trasparenze
glEnable(GL_BLEND)
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)

# Setup illuminazione
glEnable(GL_LIGHTING)
glEnable(GL_LIGHT0)
glEnable(GL_COLOR_MATERIAL)
glColorMaterial(GL_FRONT_AND_BACK, GL_AMBIENT_AND_DIFFUSE)
```

### Ogni Frame

```python
# Pulisci schermo e depth buffer
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)

# Imposta colore di sfondo (cielo blu)
glClearColor(0.53, 0.81, 0.92, 1.0)

# Setup camera
glMatrixMode(GL_PROJECTION)
glLoadIdentity()
gluPerspective(45, aspect_ratio, 0.1, 5000.0)

glMatrixMode(GL_MODELVIEW)
glLoadIdentity()
gluLookAt(cam_distance, cam_height, cam_distance,
          0, 0, 0,
          0, 1, 0)
```

### Disegno Geometria

```python
# Disegna faccia superiore tile
glBegin(GL_QUADS)
glColor3f(0.3, 0.6, 0.3)  # Verde
glVertex3f(x, y, z)       # Vertice 1
glVertex3f(x+w, y, z)     # Vertice 2
glVertex3f(x+w, y, z+d)   # Vertice 3
glVertex3f(x, y, z+d)     # Vertice 4
glEnd()

# Disegna bordi wireframe
glColor3f(0.0, 0.0, 0.0)  # Nero
glLineWidth(5.0)          # Spessore linea
glBegin(GL_LINES)
glVertex3f(x1, y1, z1)
glVertex3f(x2, y2, z2)
glEnd()
```

## GLU: OpenGL Utility Library

### Cos'è GLU?

Una libreria di funzioni di utilità che semplifica operazioni comuni:

```python
from OpenGL.GLU import *

# Invece di calcolare matrici complesse a mano:
gluPerspective(fov, aspect, near, far)
gluLookAt(eye_x, eye_y, eye_z,
          center_x, center_y, center_z,
          up_x, up_y, up_z)
```

### Funzioni GLU Utilizzate

**gluPerspective**
Crea una matrice di proiezione prospettica:

```python
gluPerspective(
    45,           # Field of View (angolo visuale)
    1.5,          # Aspect ratio (larghezza/altezza)
    0.1,          # Near clipping plane (minima distanza)
    5000.0        # Far clipping plane (massima distanza)
)
```

**gluLookAt**
Posiziona la camera:

```python
gluLookAt(
    800, 450, 800,  # Posizione camera (eye)
    0, 0, 0,        # Punto guardato (center)
    0, 1, 0         # Direzione "su" (up)
)
```

## Performance e Ottimizzazione

### Vertex Arrays (Non usati nel progetto, ma utili)

Invece di:
```python
# Lento: una chiamata per vertice
glBegin(GL_QUADS)
for vertex in vertices:
    glVertex3f(vertex.x, vertex.y, vertex.z)
glEnd()
```

Potresti usare:
```python
# Veloce: batch di vertici
glEnableClientState(GL_VERTEX_ARRAY)
glVertexPointer(3, GL_FLOAT, 0, vertex_array)
glDrawArrays(GL_QUADS, 0, vertex_count)
```

### VBO - Vertex Buffer Objects

Per progetti più grandi, usa VBO per tenere i dati sulla GPU:

```python
# Crea buffer sulla GPU
vbo = glGenBuffers(1)
glBindBuffer(GL_ARRAY_BUFFER, vbo)
glBufferData(GL_ARRAY_BUFFER, vertex_data, GL_STATIC_DRAW)
```

Il nostro progetto è abbastanza piccolo (400 tile) da non necessitare ottimizzazioni avanzate!

## Double Buffering

### Il Problema del Flickering

Senza double buffering, vedi il disegno in progress:

```
Frame 1: ████░░░░  ← Disegno incompleto
Frame 2: ████████  ← Completato
Frame 3: ████░░░░  ← Di nuovo incompleto
         ↓
Risultato: Flicker fastidioso!
```

### La Soluzione

Usa due buffer:
- **Front Buffer**: Quello visibile
- **Back Buffer**: Dove disegni

```python
# Setup con double buffer
pygame.display.set_mode((width, height), DOUBLEBUF | OPENGL)

# Ogni frame:
# 1. Disegna sul back buffer
draw_everything()

# 2. Scambia front e back buffer
pygame.display.flip()  # Swap istantaneo!
```

Risultato: Animazione fluida! ✨

## Riepilogo OpenGL

### Concetti Chiave

✅ **State Machine**: Imposti stati globali
✅ **Pipeline**: Vertici → Trasformazioni → Pixel
✅ **Primitive**: Points, Lines, Triangles, Quads
✅ **Matrici**: Projection (come) e ModelView (cosa/dove)
✅ **Illuminazione**: Ambient + Diffuse
✅ **Depth Buffer**: Gestisce sovrapposizioni
✅ **Double Buffering**: Animazioni fluide

### Comandi Essenziali

```python
# Setup
glEnable(GL_DEPTH_TEST)
glEnable(GL_LIGHTING)
glEnable(GL_LIGHT0)

# Ogni frame
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
glMatrixMode(GL_PROJECTION)
glLoadIdentity()
gluPerspective(...)
glMatrixMode(GL_MODELVIEW)
glLoadIdentity()
gluLookAt(...)

# Disegno
glBegin(GL_QUADS)
glColor3f(r, g, b)
glVertex3f(x, y, z)
glEnd()

# Swap buffer
pygame.display.flip()
```

### Flusso Applicazione

```
1. Inizializza Pygame + OpenGL
2. Setup stati OpenGL (lighting, depth)
3. Loop principale:
   a. Gestisci input
   b. Aggiorna stato (camera, ecc.)
   c. Pulisci buffer
   d. Setup matrici camera
   e. Disegna geometria
   f. Swap buffer
4. Chiudi applicazione
```

---

**Prossimo Capitolo**: [Perlin Noise: Generazione Procedurale →](04-perlin-noise.md)

[← Capitolo Precedente](02-concetti-base.md) | [Torna all'indice](README.md)