FOSFENO/docs/mapping.md

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.

Se aplica a los motores que corren en el navegador: Butterchurn, Hydra, Shaders y Mezclador. (projectM nativo aún no; ver 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.