FOSFENO/docs/mapping.md

# Projection mapping

> **Pestañas de capa.** Cada capa tiene su propia pestaña arriba, junto a
> MOTORES y MAPPING, y el botón **+ CAPA** crea una y te deja ya dentro de
> ella. Esa vista enseña solo la previsualización y los ajustes de *esa* capa:
> es la forma de trabajar cuando hay varias, sin ir y volver a la lista.
>
> **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.

<div align="center">
  <img src="assets/mapping.png" alt="La pestaña MAPPING del panel" width="720">
</div>

## 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.

<div align="center">
  <img src="assets/capas.png" alt="Tres capas con visuales distintos" width="820">
</div>

### 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).