Guía de desarrollo de decal proyectado

Descripción general de la función

La proyección de decal (Decal Projector) proyecta una imagen 2D sobre la superficie de la nube de puntos 3DGS como un proyector de diapositivas. El proyector es un frustum de perspectiva fijo en el espacio de mundo; la nube de puntos dentro del frustum queda cubierta por el color del decal, y la nube de puntos fuera del frustum no se ve afectada. El decal es un estado de sombreado global que tiene un efecto de sombreado coherente en toda la escena 3DGS.

Además de la proyección básica, se puede activar opcionalmente el culling por oclusión. Por defecto, el decal es similar a una radiografía: dado que el 3DGS en sí no tiene concepto de superficie, el decal penetra hasta las caras traseras ocluidas por los objetos frontales y atraviesa toda la escena 3DGS. Después de activar el culling por oclusión, solo se colorea la superficie frontal orientada hacia el proyector, mientras que las caras traseras ocluidas y las escenas ocluidas ya no se colorean, produciendo un efecto realista de proyector de diapositivas.

Nota:

El decal y el culling por oclusión solo surten efecto en PC / Mac (pipeline URP). Llamar a las interfaces relacionadas en plataformas móviles o VR es ignorado por el SDK, que imprime un log de advertencia. No necesitas hacer comprobaciones de plataforma en el lado de negocio, pero no esperes ver el efecto en esas plataformas.

Paso 1: Crear la escena y los GameObjects

Crea una escena completamente nueva en Unity. Unity crea Main Camera y Directional Light por defecto.

Configurar Main Camera

Selecciona Main Camera en la ventana Jerarquía y establece sus propiedades en la ventana Inspector como se muestra a continuación.

Establecer las propiedades de Main Camera

Crear LCCManager

Haz clic con el botón derecho en un área vacía de la ventana Jerarquía, selecciona Create Empty en el menú emergente para crear un GameObject vacío, nómbralo LCCManager, normaliza su Transform y añádele el script LCCManager mediante Agregar componente.

Crear el GameObject LCCManager y añadir el script LCCManager

Crear LCCRenderer

Haz clic con el botón derecho en un área vacía de la ventana Jerarquía, selecciona Create Empty para crear un GameObject vacío, nómbralo LCCRenderer y establece su Transform como Rotation.x = -90 y Scale.x = -1.

Crear LCCRenderer y establecer su Transform (Rotation.x = -90, Scale.x = -1)

Nota:

Los ajustes de Transform del GameObject LCCRenderer (Rotation.x = -90, Scale.x = -1) lo alinean con el sistema de coordenadas de los datos LCC. Para más detalles sobre la alineación del sistema de coordenadas, consulta "Sistema de coordenadas de los datos LCC" en Introducción al SDK de Unity.

Crear Projector

Haz clic con el botón derecho en un área vacía de la ventana Jerarquía, selecciona Create Empty para crear un GameObject vacío llamado Projector. El propósito de crear este objeto vacío es usar su componente Transform para controlar la posición y orientación del proyector; después de asociarlo con el código del script, puedes ajustar las propiedades del proyector en tiempo de ejecución. El proyector proyecta a lo largo de su dirección +Z, y sus propiedades pueden establecerse según sea necesario.

Crear el GameObject vacío Projector como proyector (+Z es la dirección de proyección)

Paso 2: Añadir un Render Feature

1. En la barra de menús de Unity, selecciona Archivo → Ajustes del proyecto, elige Gráficos a la izquierda y confirma el Default Render Pipeline Asset actual. Este ejemplo usa URP (Universal Render Pipeline Asset).

Confirmar el Default Render Pipeline Asset en los ajustes de Gráficos

2. Haz clic en ese Asset, localiza el archivo de asset correspondiente en la ventana Proyecto y encuentra su Renderer asociado (URP_Renderer.asset en este ejemplo).

3. Selecciona ese archivo de asset del Renderer, haz clic en Add Renderer Feature en la ventana Inspector y añade el Decal Depth Feature.

Añadir el Decal Depth Feature al URP Renderer

Nota:

Decal Depth Feature es un requisito previo para el culling por oclusión. Si solo usas la proyección básica (decal tipo radiografía), no necesitas añadirlo; pero para habilitar el culling por oclusión, primero debes registrar este Feature en el URP Renderer Asset, de lo contrario el mapa de profundidad de oclusión no se generará y la oclusión no surtirá efecto.

Paso 3: Escribir el script

Crea un nuevo script C# llamado Decal.cs. El código completo a continuación simula la perspectiva del integrador y cubre los 7 métodos relacionados con el decal (5 para la proyección básica + 2 para el culling por oclusión); puede copiarse directamente en tu proyecto.

using LCCCore;
using UnityEngine;

/// <summary>
/// Proyección de decal — ejemplo mínimo de uso para desarrolladores.
///
/// Este script simula un "script integrador": solo llama a las API públicas de LCCManager y no toca el interior del SDK.
/// Cubre las 7 API de decal:
///   Proyección base (5): SetDecalEnabled / SetDecalTexture / SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade
///   Oclusión por culling (2): SetDecalOcclusion / SetDecalOcclusionSettings
///
/// Pasos de uso:
///   1) Crea un GameObject vacío y adjunta este script;
///   2) En el Inspector, arrastra el LCCManager de la escena a m_manager;
///   3) Establece m_filePath a una ruta de escena LCC válida;
///   4) Arrastra la imagen a proyectar a m_decalTexture (se recomienda habilitar Read/Write en sus ajustes de importación);
///   5) Arrastra un objeto vacío a m_projector como proyector (déjalo vacío para usar este objeto); su eje +Z es la dirección de proyección;
///   6) Play. Después de que la escena termine de cargarse, el decal se activa automáticamente; arrastra el proyector para ver el decal en la nube de puntos en tiempo real.
///
/// Nota de plataforma: el decal y el culling por oclusión solo surten efecto en PC/Mac (URP). Las llamadas en móvil/VR son ignoradas por el SDK y registradas como advertencias.
/// </summary>
public class Decal : MonoBehaviour
{
    [Header("Requerido")]
    [Tooltip("La instancia LCCManager en la escena")]
    public LCCManager m_manager;
    [Tooltip("Una ruta de escena LCC válida")]
    public string m_filePath;
    [Tooltip("La imagen del decal a proyectar. RGB=color, A=máscara propia del decal")]
    public Texture2D m_decalTexture;

    [Header("Proyector (proyecta a lo largo de +Z)")]
    [Tooltip("Pose del proyector. Déjalo vacío para usar el transform de este objeto")]
    public Transform m_projector;
    [Range(1f, 179f)] public float m_fov = 60f;
    [Tooltip("Relación de aspecto de la proyección; <=0 usa automáticamente la relación de aspecto de la imagen del decal")]
    public float m_aspect = 0f;
    public float m_near = 0.1f;
    public float m_far = 100f;

    [Header("Apariencia del decal")]
    [Range(0f, 1f)] public float m_opacity = 1.0f;
    [Range(0f, 0.5f)][Tooltip("Ancho de desvanecimiento del borde (relación UV). 0 = borde duro")]
    public float m_edgeFade = 0.1f;
    [Tooltip("Actualiza la proyección cada fotograma, para que puedas arrastrar el proyector / ajustar parámetros en tiempo de ejecución")]
    public bool m_updateEveryFrame = true;

    [Header("Oclusión por culling (solo PC/Mac)")]
    [Tooltip("Cuando está activada, los puntos orientados hacia atrás/ocluidos detrás de la geometría frontal ya no son coloreados por el decal (efecto de proyector de diapositivas); cuando está desactivada es tipo radiografía")]
    public bool m_occlusion = false;
    [Range(0f, 1f)][Tooltip("Umbral de opacidad: solo los splats con opacidad >= este valor contribuyen al mapa de profundidad, filtrando puntos flotantes/nebulosos. 0 = todos participan")]
    public float m_occlusionCutoff = 0f;
    [Range(0f, 0.5f)][Tooltip("Tolerancia de profundidad relativa. Demasiado pequeña -> autooclusión cerca de la superficie; demasiado grande -> coloración de radiografía filtrada. Por defecto 0.05")]
    public float m_occlusionBias = 0.05f;
    [Range(0, 16)][Tooltip("Tope del radio de huella cuadrada (px), el control principal para eliminar la filtración de radiografía. 0 = un solo texel, por defecto 2")]
    public int m_occlusionFootprint = 2;
    [Tooltip("Resolución del mapa de profundidad (px, potencia de dos 256~4096). Bájala para rellenar huecos en ángulos rasantes. Por defecto 1024")]
    public int m_occlusionResolution = 1024;

    // -- Estado en tiempo de ejecución --
    private bool m_loaded;
    private bool m_lastOcclusion;
    private float m_lastCutoff = float.NaN;
    private float m_lastBias = float.NaN;
    private int m_lastFootprint = -1;
    private int m_lastResolution = -1;

    void Start()
    {
        if (m_manager == null || string.IsNullOrEmpty(m_filePath))
        {
            Debug.LogError("[DecalDemo] m_manager o m_filePath no están asignados.");
            enabled = false;
            return;
        }

        // 1) Inicializa el pipeline de renderizado al modo editor de una sola escena de PC
        m_manager.SetPlatformType(PlatformType.PC);
        m_manager.SwitchRenderPass(ActiveRenderMode.SingleRender);
        m_manager.SetEditorMode(true);

        // 2) Carga la escena de nube de puntos y luego activa el decal tras la finalización (el decal es un estado global; configurarlo después de que la escena esté lista es lo más seguro)
        var renderer = m_manager.GetRender(this.transform);
        Debug.Log($"[DecalDemo] Iniciando carga: {m_filePath}");
        renderer.Load(m_filePath,
            _ => { /* devolución de llamada de progreso, sin usar en el ejemplo */ },
            OnSceneLoaded);
    }

    private void OnSceneLoaded()
    {
        Debug.Log("[DecalDemo] Carga completa, activando la proyección del decal.");

        // -- Proyección base: 5 API --
        m_manager.SetDecalTexture(m_decalTexture);   // contenido del decal
        m_manager.SetDecalOpacity(m_opacity);        // opacidad general
        m_manager.SetDecalEdgeFade(m_edgeFade);      // desvanecimiento del borde
        ApplyProjection();                           // pose del proyector (internamente llama a SetDecalProjection)
        m_manager.SetDecalEnabled(true);             // activa el decal (keyword _DECAL)

        // -- Oclusión por culling: 2 API -- debe ir después de ApplyProjection (el mapa de profundidad necesita una VP válida del proyector)
        m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
        m_manager.SetDecalOcclusion(m_occlusion);
        CacheOcclusionState();

        m_loaded = true;
    }

    /// <summary>
    /// Solo para demostración. En proyectos reales, para un mejor rendimiento no necesitas llamar a
    /// SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade cada fotograma en Update();
    /// solo llama a la API correspondiente cuando cambie el parámetro.
    /// </summary>
    void Update()
    {
        if (!m_loaded) return;

        // alterna la oclusión en tiempo de ejecución
        if (m_occlusion != m_lastOcclusion)
        {
            m_manager.SetDecalOcclusion(m_occlusion);
            m_lastOcclusion = m_occlusion;
        }

        // si cambió algún parámetro de calidad de oclusión -> envía la estructura una vez
        if (!Mathf.Approximately(m_occlusionCutoff, m_lastCutoff) ||
            !Mathf.Approximately(m_occlusionBias, m_lastBias) ||
            m_occlusionFootprint != m_lastFootprint ||
            m_occlusionResolution != m_lastResolution)
        {
            m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
            CacheOcclusionState();
        }

        // actualiza proyector / apariencia cada fotograma para una depuración en tiempo real cómoda
        if (!m_updateEveryFrame) return;
        m_manager.SetDecalOpacity(m_opacity);
        m_manager.SetDecalEdgeFade(m_edgeFade);
        ApplyProjection();
    }

    /// <summary>Construye la matriz de proyección a partir de la pose actual del proyector y los parámetros de perspectiva.</summary>
    private void ApplyProjection()
    {
        Transform p = m_projector != null ? m_projector : this.transform;
        float aspect = m_aspect > 0f
            ? m_aspect
            : (m_decalTexture != null ? (float)m_decalTexture.width / m_decalTexture.height : 1f);
        m_manager.SetDecalProjection(p.position, p.rotation, m_fov, aspect, m_near, m_far);
    }

    /// <summary>Reúne los 4 parámetros de oclusión en una estructura.</summary>
    private DecalOcclusionSettings BuildOcclusionSettings()
    {
        return new DecalOcclusionSettings
        {
            opacityCutoff  = m_occlusionCutoff,
            depthBias      = m_occlusionBias,
            footprintMaxPx = m_occlusionFootprint,
            resolution     = m_occlusionResolution,
        };
    }

    private void CacheOcclusionState()
    {
        m_lastOcclusion  = m_occlusion;
        m_lastCutoff     = m_occlusionCutoff;
        m_lastBias       = m_occlusionBias;
        m_lastFootprint  = m_occlusionFootprint;
        m_lastResolution = m_occlusionResolution;
    }

    // -- Puntos de entrada de depuración cómodos (clic derecho en el Inspector) --
    [ContextMenu("Activar decal")]  private void DecalOn()  { m_manager?.SetDecalEnabled(true); }
    [ContextMenu("Desactivar decal")] private void DecalOff() { m_manager?.SetDecalEnabled(false); }
    [ContextMenu("Activar oclusión")]  private void OcclusionOn()  { m_occlusion = true;  m_manager?.SetDecalOcclusion(true);  m_lastOcclusion = true; }
    [ContextMenu("Desactivar oclusión")] private void OcclusionOff() { m_occlusion = false; m_manager?.SetDecalOcclusion(false); m_lastOcclusion = false; }
}

Nota:

El decal es un estado de sombreado global y debe configurarse después de que la escena LCC termine de cargarse (es decir, en la devolución de llamada onComplete).

El ejemplo coloca SetDecalTexture / SetDecalProjection / SetDecalEnabled en la devolución de llamada de finalización de Load (OnSceneLoaded) para evitar configurarlos antes de que la nube de puntos esté lista.

Los métodos relacionados con el culling por oclusión SetDecalOcclusionSettings / SetDecalOcclusion deben llamarse después de ApplyProjection (es decir, SetDecalProjection), porque el mapa de profundidad de oclusión necesita una matriz de vista-proyección del proyector válida.

Paso 4: Adjuntar el script y configurar las propiedades

1. Adjunta el script Decal.cs al GameObject LCCRenderer en la ventana Jerarquía.
2. En la ventana Inspector, arrastra el GameObject LCCManager a la propiedad Manager del script.
3. Arrastra el GameObject Projector a la propiedad Projector del script.
4. Rellena la ruta del archivo LCC en la propiedad File Path del script y arrastra la imagen de textura del decal a la propiedad Decal Texture.
5. Otros parámetros de propiedad pueden ajustarse según sea necesario; el significado de cada propiedad se muestra en la tabla siguiente.

Ajustes de propiedad del Inspector para el script Decal

Paso 5: Ejecutar y observar el efecto

Haz clic en el botón Play de Unity. Después de que la escena termine de cargarse, el decal se activa automáticamente. Cuando Update Every Frame está marcado, puedes arrastrar directamente el objeto proyector en la vista Scene durante el tiempo de ejecución y ver el decal moverse sobre la superficie 3DGS en tiempo real; ajustar parámetros como Opacity y Edge Fade también surte efecto inmediatamente. El menú contextual del componente del script también proporciona cuatro atajos — Activar/Desactivar decal y Activar/Desactivar oclusión — para verificar cómodamente el efecto de activación/desactivación por separado.

Decal proyectado sobre la superficie 3DGS tras la ejecución (proyección básica, penetración tipo radiografía)

Tras activar el culling por oclusión, solo se colorea la superficie frontal orientada hacia el proyector (efecto de proyector de diapositivas)

Preguntas frecuentes: desactivar el modo de compatibilidad

Si la ventana Console de Unity informa de errores y no aparece ningún efecto de decal, desactiva el modo de compatibilidad: abre el panel de ajustes mediante Editar → Ajustes del proyecto → Gráficos, selecciona la pestaña URP y no marques la casilla situada después de Render Graph → Compatibility Mode (Render Graph Disabled).

No marcar el modo de compatibilidad de Render Graph (Render Graph Disabled)

Culling por oclusión y ajuste

El culling por oclusión debe habilitarse después de que el proyector esté configurado. El ejemplo llama primero a SetDecalProjection en la devolución de llamada de finalización de carga de la escena y luego llama a SetDecalOcclusionSettings y SetDecalOcclusion, para asegurar que el mapa de profundidad de oclusión obtiene una matriz de vista-proyección del proyector válida. En tiempo de ejecución, activa la casilla Occlusion en el Inspector para ver los bloques penetrados descartados y solo la superficie frontal orientada hacia el proyector retenida.

Requisito previo:

Antes de habilitar el culling por oclusión, el Decal Depth Feature ya debe estar registrado en el URP Renderer Asset (en este proyecto se ha escrito en URP_Renderer.asset como sub-activo). Si no está registrado, el mapa de profundidad de oclusión no se generará y la oclusión no surtirá efecto.

La calidad de la oclusión se controla mediante cuatro parámetros, entregados todos a la vez a través de una estructura. Los cuatro son mutuamente ortogonales; ajústalos según la tabla siguiente:

Pasos clave

Los pasos clave para implementar el decal proyectado:

1. Crea el objeto vacío Projector en la escena como proyector; su eje +Z es la dirección de proyección.
2. Si se necesita culling por oclusión, asegúrate de que el Decal Depth Feature se ha añadido al URP Renderer.
3. Después de que la escena LCC termine de cargarse, establece la textura del decal, la apariencia y la pose del proyector en orden, y luego activa el decal (SetDecalEnabled(true)).
4. El culling por oclusión SetDecalOcclusionSettings / SetDecalOcclusion debe llamarse después de SetDecalProjection.

API relacionadas con el decal

Los siguientes métodos están todos en la clase de fachada LCCManager y solo surten efecto en PC / Mac (pipeline URP); las llamadas en móvil / VR se ignoran y se imprime una advertencia.

SetDecalEnabled

// Valor de retorno: void
public void SetDecalEnabled(bool enable)

Activa o desactiva la proyección del decal. Cuando está activada, los parámetros de opacidad / desvanecimiento de borde almacenados en caché se envían a la GPU y se habilita la keyword de shader _DECAL. El decal es un estado global fijo en el mundo, coherente para todas las cámaras. También debes llamar a SetDecalTexture y SetDecalProjection para establecer el contenido y la pose del proyector.

Ejemplo de uso:

m_manager.SetDecalEnabled(true);
m_manager.SetDecalTexture(decalTex);
m_manager.SetDecalProjection(projectorPos, projectorRot, 60f, 1.778f, 0.1f, 20f);

Notas:

• Cuando está desactivada, solo se desactiva la keyword _DECAL; la textura / parámetros en caché no se limpian.

SetDecalTexture

// Valor de retorno: void
public void SetDecalTexture(Texture2D tex)

Establece la textura del decal. RGB es el color y A es la máscara propia del decal, que se multiplica con la opacidad global y el desvanecimiento del borde.

Ejemplo de uso:

m_manager.SetDecalTexture(logoTex);

Notas:

• Pasar null limpia la referencia global de la textura.

SetDecalProjection

// Valor de retorno: void
public void SetDecalProjection(Vector3 pos, Quaternion rot, float fov, float aspect, float near, float far)

Establece la pose y los parámetros de perspectiva del proyector del decal. El proyector proyecta a lo largo de su dirección frontal (+Z), y los puntos dentro del frustum quedan cubiertos por el decal.

Ejemplo de uso:

m_manager.SetDecalProjection(new Vector3(0, 10, 0), Quaternion.Euler(90, 0, 0), 60f, 1.778f, 0.1f, 20f);

Notas:

• Si SetDecalOcclusion(true) ya está activado, este método reenvía síncronamente la nueva VP / vista al Decal Depth Feature.

SetDecalOpacity

// Valor de retorno: void
public void SetDecalOpacity(float opacity)

Establece la opacidad general del decal, enviándola inmediatamente a la GPU y almacenándola en caché para reutilizarla la próxima vez que se llame a SetDecalEnabled(true).

Ejemplo de uso:

m_manager.SetDecalOpacity(0.8f);

Notas:

• Rango [0, 1]; los valores fuera del rango se limitan automáticamente.

SetDecalEdgeFade

// Valor de retorno: void
public void SetDecalEdgeFade(float edgeFade)

Establece el ancho de desvanecimiento del borde del decal. 0 es un borde duro, y cuanto mayor es el valor, más suave es la transición del borde.

Ejemplo de uso:

m_manager.SetDecalEdgeFade(0.1f);

Notas:

• Rango [0, 0.5); los valores fuera del rango se limitan automáticamente.

SetDecalOcclusion

// Valor de retorno: void
public void SetDecalOcclusion(bool enable)

Activa o desactiva el culling por oclusión del decal (basado en el mapa de profundidad del proyector), que es ortogonal a la función de sombras y se activa/desactiva de forma independiente. SetDecalProjection debería haberse llamado para configurar el proyector antes de habilitarlo, de lo contrario el mapa de profundidad no tiene una VP válida.

Ejemplo de uso:

m_manager.SetDecalOcclusion(true);

Notas:

• Solo compatible con URP (las llamadas en el pipeline Built-in son una operación nula e imprimen un log).
• Requiere que el Decal Depth Feature esté registrado en el URP Renderer Asset.
• Depende de los parámetros de calidad configurados por SetDecalOcclusionSettings.

SetDecalOcclusionSettings

// Valor de retorno: void
public void SetDecalOcclusionSettings(DecalOcclusionSettings settings)

Establece todos los parámetros de calidad del culling por oclusión del decal a la vez (consulta la estructura a continuación y la tabla "Culling por oclusión y ajuste" para el significado de los cuatro elementos).

Ejemplo de uso:

m_manager.SetDecalOcclusionSettings(DecalOcclusionSettings.Default);
m_manager.SetDecalOcclusionSettings(new DecalOcclusionSettings {
    opacityCutoff = 0.1f,
    depthBias = 0.05f,
    footprintMaxPx = 2,
    resolution = 1024
});

Notas:

• Puede ajustarse en cualquier momento; los parámetros se envían inmediatamente a la GPU y al Decal Depth Feature.
• Cambiar resolution provoca una reconstrucción del RT del mapa de profundidad.

Estructuras de datos relacionadas

DecalOcclusionSettings

public struct DecalOcclusionSettings {
    public float opacityCutoff;   // [0,1] opacidad mínima para que un splat participe en el mapa de profundidad, por defecto 0 (todos participan)
    public float depthBias;       // relación de tolerancia de profundidad relativa, por defecto 0.05
    public int   footprintMaxPx;  // tope del radio de huella cuadrada (px), 0~16, por defecto 2
    public int   resolution;      // resolución del mapa de profundidad (px, potencia de dos, 256~4096), por defecto 1024

    public static DecalOcclusionSettings Default { get; } // cutoff=0, bias=0.05, footprint=2, resolution=1024
}

Usada por SetDecalOcclusionSettings(); el valor por defecto puede obtenerse mediante DecalOcclusionSettings.Default.

Notas

• Solo eficaz en PC / Mac. Las llamadas a las interfaces relacionadas con el decal en plataformas móviles y VR se ignoran e imprimen una advertencia. No necesitas hacer comprobaciones de plataforma en el lado de negocio, pero no esperes ver el efecto en esas plataformas.
• Se recomienda establecer el decal después de que la escena termine de cargarse. El decal es un estado de sombreado global; el ejemplo coloca SetDecalTexture / SetDecalProjection / SetDecalEnabled en la devolución de llamada de finalización de Load para evitar configurarlos antes de que la nube de puntos esté lista.
• El culling por oclusión depende de dos requisitos previos. Primero, el URP Renderer Asset ha registrado el Decal Depth Feature; segundo, se ha llamado a SetDecalProjection para configurar el proyector. La oclusión no surte efecto si falta cualquiera de los dos.
• La proyección estática tiene un coste adicional casi nulo. El mapa de profundidad de oclusión solo se recalcula cuando cambia la pose del proyector o la nube de puntos; cuando el proyector está inmóvil, no hay cómputo adicional por fotograma.