Cómo depurar errores de renderizado con código y capturas
Su objeto aparece en el lugar equivocado, pero el sombreador se compila. Una captura de pantalla muestra el síntoma; el código muestra varias causas plausibles. Pedirle a la IA que "arregle la imagen" sin la cámara, las matrices o el resultado esperado fomenta una suposición convincente.
Prepare un paquete de evidencia de renderizado
Incluya el renderizador/API, las etapas de sombreado relevantes, los valores de las variables uniform, la geometría, la ventana gráfica, la cámara, el resultado esperado, el fotograma real y la acción de reproducción. Registre los errores de gráficos y compile/vincule diagnósticos como observaciones, no como un resumen que diga "todo está bien".
| Evidencia | Contenido útil | Lo que una captura de pantalla por sí sola no puede establecer |
|---|---|---|
| Fotograma esperado y obtenido | Misma cámara y resolución, región afectada marcada | ¿Qué transformación o estado causó la diferencia? |
| Shader y variables uniform | Revisión exacta, convención matricial, valores | Si la aplicación cargó los valores previstos |
| Configuración de dibujado | Geometría, diseño de atributos, estados de profundidad, culling y mezcla | ¿Qué objetos fueron realmente dibujados? |
| Reproducción | Escena y pasos mínimos | Si un parche sugerido soluciona otra escena |
Una textura faltante y una iluminación incorrecta pueden parecer similares en tamaño de miniatura. Proporcione un recorte sin comprimir cuando sea práctico y evite cambiar la cámara entre fotogramas de comparación.
Un ejemplo de orden de transformación con una expectativa verificable
projection * view * model * position, y se aplica primero la transformación situada más a la derecha.Supongamos que el sombreador contiene:
gl_Position = uProjection * uModel * uView * vec4(position, 1.0);(1,0,0,1), el resultado de recorte previsto es (0,0.6,0,1):Model: (1,0) -> (3,0)
View: (3,0) -> (0,3)
Projection: (0,3) -> (0,0.6)
Wrong order: View (1,0)->(0,1), Model ->(2,1), Projection ->(0.4,0.2)Solicite hipótesis, reproducción y parche mínimo.
Investigue la discrepancia en la representación proporcionada.
Utilice el sombreador, el estado del host, el comportamiento esperado, el fotograma real y la revisión.
Trate las imágenes como observaciones, no como prueba de una causa raíz en particular.
Retorno:
1. síntoma observado y la evidencia que lo respalda;
2. hipótesis clasificadas, con una prueba discriminante para cada una;
3. la prueba más pequeña para la hipótesis principal;
4. un parche sólo si la prueba respalda la afirmación;
5. Faltan uniformes, estado o contexto que impiden una conclusión.
Utilice la convención de matriz/vector indicada.
No reescriba el renderizador ni cambie la cámara para ocultar el defecto.
No afirme que ha ejecutado pruebas si solo las ha propuesto.
Entradas: paquete de evidencia y contrato de transformación requerido.Para este ejemplo, el parche candidato es:
gl_Position = uProjection * uView * uModel * vec4(position, 1.0);Aporte la convención matricial y el shader defectuoso. Pida una hipótesis y un parche mínimo; distinga (0,0.6) de (0.4,0.2) con la prueba numérica antes de revisar el render real.
Ejecute una pequeña verificación numérica antes de juzgar el fotograma.
El siguiente JavaScript refleja la parte bidimensional de las transformaciones de este ejemplo:
const model = ([x, y]) => [x + 2, y];
const view = ([x, y]) => [-y, x];
const projection = ([x, y]) => [x * 0.2, y * 0.2];
const correct = projection(view(model([1, 0])));
const wrong = projection(model(view([1, 0])));
if (Math.abs(correct[0]) > 1e-9 || Math.abs(correct[1] - 0.6) > 1e-9) {
throw new Error("Unexpected reference transform");
}
if (Math.abs(wrong[0] - correct[0]) < 1e-9 &&
Math.abs(wrong[1] - correct[1]) < 1e-9) {
throw new Error("Fixture does not distinguish transform order");
}Cuando la misma captura de pantalla podría significar otro error
| Síntoma | Prueba para distinguir causas |
|---|---|
| Cambios de posición con el movimiento de la cámara | Verificar transformaciones y valores cargados con respecto a un punto conocido |
| El objeto desaparece de un lado | Inspeccionar el orden de los vértices y el culling y ver la orientación |
| Posición correcta pero oclusión incorrecta | Inspeccionar el estado de conexión, limpieza y comparación de profundidad |
| Una textura parece estirada o invertida | Inspeccionar las coordenadas UV, la orientación de la imagen y los datos del muestreador |
| Sólo se diferencian las pantallas de alta densidad | Comparar el tamaño del búfer de dibujo con el tamaño de la ventana gráfica y CSS |
Cambie una condición a la vez. Desactivar el culling puede hacer visible la geometría, pero no establece que desactivarla sea la solución final correcta. Guarde el experimento y su interpretación por separado.
Mantenga una escena de regresión con la solución
Mantener un caso en el que la traslación y la rotación no conmuten; Las matrices de identidad ocultarían el error en este ejemplo. Agregue movimiento normal de la cámara y geometría representativa después de que pase el caso mínimo. Compare la misma revisión de la escena y anote cualquier artefacto restante como un tema aparte.
Preguntas frecuentes
¿Puede una captura de pantalla identificar la causa raíz exacta?
Generalmente proporciona un síntoma y una ubicación. El código, el estado y la reproducción distinguen causas en competencia.
¿Un sombreador compilado demuestra que las matemáticas son correctas?
No. Las expresiones válidas pueden aplicar transformaciones en el orden incorrecto.
¿Debería probar todos los parches sugeridos a la vez?
Utilice una hipótesis y pruébela a la vez para que el resultado tenga una causa interpretable.
¿La verificación de JavaScript verifica la salida de la GPU?
Comprueba la aritmética indicada. La representación y la validación del estado del host son pasos separados.
¿Debería el modelo recibir todo el repositorio?
Comience con la escena y el estado relevante necesarios para reproducir la discrepancia. Agregue dependencias cuando una hipótesis las requiera.
¿Qué pertenece al registro final de errores?
Revisión, entradas, comportamiento esperado y observado, experimento, parche aceptado, comprobaciones de regresión e incertidumbre restante.
Fuentes
- Khronos: transformación de vértices: etapas de coordenadas.
- MDN: uniformes de matriz: Requisitos de carga de WebGL.
