# Projection mapping
> **Las capas se manejan desde MOTORES.** La fila *Dónde se ve* de la pestaña
> MOTORES lista `SALIDA` y una entrada por capa; eligiendo una, sus ajustes
> salen ahí mismo y las pastillas la apuntan a ella. MAPPING queda para lo
> suyo: **colocar y deformar** las capas sobre la superficie física. Ver
> `uso.md`.
>
> **Visuales de projectM en una capa.** La fuente "Visuales MilkDrop" tiene
> ahora un selector de **biblioteca**: los ~100 presets de Butterchurn, o los
> **9795 `.milk` de projectM** (categoría / visual / variante, o "uno al
> azar"). Los `.milk` se traducen a Butterchurn en el propio navegador al
> elegirlos. Ver `pendiente.md` punto 2 para el detalle y sus límites.
FOSFENO puede **deformar las visuales** para encajarlas en superficies físicas
(una pared en ángulo, cajas, un objeto, varias zonas de una fachada) en vez de
proyectar un simple rectángulo. Todo se hace **desde el panel**, arrastrando con
el ratón o el dedo, y se **guarda solo**.
Y no es una sola imagen troceada: **cada zona es una capa con su propio
visual**. MilkDrop a la derecha, otro preset distinto a la izquierda y un vídeo
en el centro, cada uno en su sitio y a la vez. Eso está en
[Capas: un visual distinto en cada zona](#capas-un-visual-distinto-en-cada-zona).
Se aplica a los motores que corren en el navegador: **Butterchurn, Hydra,
Shaders y Mezclador**. (projectM nativo aún no; ver [Limitaciones](#limitaciones).)
## Dónde está: la pestaña MAPPING
El mapping tiene **su propia pestaña**, a la derecha del título **FOSFENO**, al
lado de **MOTORES**. Están separados a propósito: MOTORES es el directo
(encendido, audio, motores) y MAPPING es el montaje. Así ni se estorban ni se
confunden.
En la pestaña MAPPING la tarjeta ocupa el ancho entero, para que la
previsualización sea grande y se puedan arrastrar los puntos con comodidad —
también con el dedo, desde el móvil.
Mientras el mapping esté activado, la pestaña lleva un **punto verde**: desde
MOTORES se ve de un vistazo que la salida se está deformando.
## En 4 pasos
1. Entra en la pestaña **MAPPING** y marca **Activar mapping**.
2. Pulsa **+ Capa**. Aparece un recuadro en la previsualización del panel (y en
el proyector).
3. **Arrastra los puntos** para encajar la forma sobre tu superficie real. Se ve
en el proyector al instante.
4. Con la capa seleccionada, en **Propiedades** eliges **qué se proyecta ahí**.
## La pestaña MAPPING por dentro
Tiene tres bloques, de arriba abajo: la **salida**, las **capas** y las
**propiedades** de la capa que tengas seleccionada.
**Salida**
- **Activar mapping** — enciende/apaga la deformación.
- **Editar en el escenario** — saca los tiradores y la malla de colores
también sobre las propias visuales (por si prefieres ajustar ahí con un
ratón). Para el uso normal **no hace falta**: con la previsualización del
panel basta, y así el proyector sale limpio. Es un modo de montaje, no un
ajuste: **arranca siempre apagado**, aunque lo dejaras puesto.
- **Previsualización** — el recuadro donde arrastras los puntos (ratón o dedo).
Cada capa lleva escrito su nombre y qué visual tiene dentro.
**Capas**
- **+ Capa** — añade una zona nueva. Sale escalonada, para que no tape a la
anterior, y queda seleccionada.
- **+ Máscara** — añade una **máscara**: un recuadro **negro** que tapa una zona
(útil para recortar el derrame de luz fuera de la superficie física).
> **Capa ≠ máscara.** Una **capa** proyecta algo (eliges qué en Propiedades);
> una **máscara** solo tapa y no lleva visual. Es la confusión más fácil: si
> creaste una máscara buscando dónde poner el visual, selecciónala y pulsa
> **Convertirla en capa** — se sustituye por una capa en el mismo sitio y con
> la misma forma.
- **Reset** — borra todas las capas y máscaras.
- La **lista** se lee como en cualquier mesa de VJ: **la de arriba es la que
queda delante** en el proyector. Cada fila tiene:
| Botón | Qué hace |
|-------|----------|
| ◉ / ○ | Enciende o apaga la capa sin borrarla |
| ▲ ▼ | La sube o la baja en el orden de pintado |
| ✕ | La borra |
**Propiedades** — nombre, qué se proyecta, opacidad, mezcla y malla. Se explican
abajo.
## Capas: un visual distinto en cada zona
Esto es lo que separa el mapping de FOSFENO de un simple recorte: **cada capa
elige su propia fuente**, así que la proyección puede llevar cosas distintas a
la vez.
| Fuente | Qué es | Coste |
|--------|--------|-------|
| **El motor de MOTORES** | Lo que esté puesto en la otra pestaña. En varias capas a la vez, todas enseñan lo mismo | ninguno |
| **Visuales MilkDrop propias** | Un Butterchurn **solo para esa capa**, con su preset. Es lo que permite dos looks de MilkDrop distintos a la vez | alto |
| **Shader GLSL** | Uno de los shaders de la librería, reaccionando al audio | medio |
| **Clip o imagen** | Un archivo de `data/videos`. En bucle y sin sonido | bajo |
| **Cámara** | La webcam | bajo |
| **Negro** | Nada: tapa la zona sin usar máscara | ninguno |
Las capas de MilkDrop y de shader **son motores de verdad funcionando**: cada
una se renderiza aparte y el mapper la estira al deformarla. Los clips y la
cámara, en cambio, **se comparten**: si dos capas usan el mismo clip, se
reproduce una sola vez.
### La receta del ejemplo
Tres zonas, tres visuales distintos:
1. **+ Capa** → nómbrala «Pared izquierda» → fuente **Visuales MilkDrop
propias** → elige un preset.
2. **+ Capa** → «Centro» → fuente **Clip o imagen** → elige tu vídeo.
3. **+ Capa** → «Pared derecha» → fuente **Visuales MilkDrop propias** → *otro*
preset, o marca **Cambiar de preset solo** para que vaya rotando.
4. Arrastra cada una a su sitio en la previsualización.
### Transiciones
Las capas de **Visuales MilkDrop** llevan su propio deslizador de
**transición (0–8 s)**: es lo que tarda un preset en disolverse en el
siguiente. A 0 el cambio es un corte seco; subiéndolo, uno se funde con el
otro sin que se note. Combinado con **Cambiar de preset solo**, la capa va
alternando visuales sola y en suave.
El fundido lo hace el propio Butterchurn mientras carga, así que no cuesta
rendimiento aparte.
### Opacidad y mezcla
Cuando dos capas se solapan, mandan estos dos ajustes:
- **Opacidad** — cuánto deja ver lo que hay debajo.
- **Mezcla** — **Normal** tapa lo de debajo; **Sumar** apila luz, así que las
zonas oscuras de la capa dejan pasar la de abajo. Sumar es lo que da los
solapes bonitos entre visuales; normal es lo que quieres cuando cada capa va
en su pared y no se tocan.
## Superficies con malla (curvar)
Una capa nueva es un cuadrilátero de 4 esquinas (corrección de perspectiva /
*keystone*). Para superficies **curvas**:
1. Selecciona la capa (toca dentro de ella en la previsualización).
2. En Propiedades, **Malla**: cada **+** la subdivide (2×2, 3×3… hasta 6×6).
3. Ahora puedes arrastrar **cualquier punto** de la rejilla (no solo las
esquinas) para curvarla y adaptarla a superficies no planas.
## Máscaras
Una máscara es un cuadrilátero **negro** que se pinta encima de todo. Sirve para
**tapar** lo que no quieres que se vea (bordes, derrames de luz, huecos entre
superficies). Añádelas con **+ Máscara** y arrastra sus esquinas igual que una
superficie.
## Dónde se guarda
La configuración se guarda sola en `data/mapping.json` y se mantiene al
reiniciar. Es **por instalación** (no se sube al repositorio). Para empezar de
cero, usa **Reset** o borra ese archivo.
## Editar en la ventana de las visuales (opcional)
Con **Editar en el escenario** activo, los tiradores también aparecen sobre las
propias visuales, con el nombre y la fuente de cada capa escritos encima. Ahí,
además, funcionan atajos de teclado:
- **doble clic** en un hueco: crea una capa nueva.
- **+ / −**: subdivide/reduce la malla de la capa seleccionada.
- **Supr**: borra la capa o máscara seleccionada.
## Cuánto aguanta
Cada capa de **MilkDrop** o de **shader** es un motor de verdad renderizando
aparte, así que tienen un coste real:
| Equipo | Capas de MilkDrop / shader | Capas de clip o cámara |
|--------|---------------------------|------------------------|
| Portátil con GPU | 3–4 sin despeinarse | muchas |
| Raspberry Pi 5 | 2, con margen justo | varias |
| Raspberry Pi 4 | 1 | unas pocas |
Cada capa se renderiza a **640×360** y el mapper la estira al deformarla: en una
zona de la proyección no se nota, y es lo que hace viable tener varias a la vez.
Si va lenta, lo primero que hay que quitar son las capas de MilkDrop de más;
clips y cámara cuestan mucho menos, y además **se comparten** entre capas.
## Limitaciones
- **projectM nativo no puede ir en una capa.** projectM corre en su propia
ventana fuera del navegador, así que el mapper no lo alcanza. Para el mismo
tipo de visual, usa la fuente **Visuales MilkDrop propias**: son los mismos
presets de MilkDrop, dentro del navegador, y además puedes tener varios
distintos a la vez. Meter la ventana nativa como capa (capturándola) está en
estudio.
- El mapping deforma y compone; no cambia el contenido de cada motor.
Cómo está montado por dentro (el compositor WebGL, las capas, el formato de las
superficies): [Arquitectura](arquitectura.md#mapping-y-capas).
