코드와 스크린샷으로 렌더링 오류를 디버깅하는 방법

물체가 엉뚱한 곳에 나오지만 셰이더는 컴파일됩니다. 스크린샷은 현상을 보여 주고 코드는 여러 원인 후보를 줍니다. 카메라·행렬·기댓값 없이 “화면을 고쳐 달라”고 하면 설득력 있는 추측을 얻기 쉽습니다.

렌더링 근거 묶음 준비하기

렌더러/API, 셰이더 단계, uniform, 기하, viewport, 카메라, 기대·실제 화면과 재현 동작을 넣습니다. 오류와 컴파일·링크 진단을 “정상”이라는 요약 대신 실제 관측으로 남깁니다.

작은 화면에서는 누락 텍스처와 조명이 비슷해 보입니다. 선명한 영역을 주고 전후 비교 중 카메라를 바꾸지 않습니다.

검증할 수 있는 변환 순서 예

문제 후보입니다.

gl_Position = uProjection * uModel * uView * vec4(position, 1.0);

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)

가설·재현·최소 패치 요구하기

셰이더·호스트 상태·기대 동작·실제 프레임·버전으로 차이를 조사하세요.
이미지는 관측이지 특정 근본 원인의 증거가 아닙니다.
현상과 근거, 가설 순위와 구별 검사, 첫 가설의 최소 테스트,
검사가 뒷받침할 때만 패치, 부족한 uniform·상태·문맥을 반환하세요.
주어진 행렬·벡터 규칙을 지키세요.
렌더러 전체를 재작성하거나 카메라 변경으로 현상을 숨기지 마세요.
제안한 테스트를 실행했다고 주장하지 마세요.
입력: 근거 묶음과 변환 규약.

이 예의 후보 패치입니다.

gl_Position = uProjection * uView * uModel * vec4(position, 1.0);

먼저 행렬 규약과 오류 셰이더를 주고 가설 하나와 최소 패치를 받습니다. 수치 예로 (0,0.6)과 (0.4,0.2)를 구별한 뒤 실제 렌더를 확인합니다.

화면을 보기 전에 수치 검사 실행하기

다음 JavaScript는 예의 2차원 변환을 나타냅니다.

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");
}

비슷한 화면의 다른 원인 구별하기

조건을 하나씩 바꿉니다. 컬링을 꺼 보이게 해도 최종 수정이 컬링 해제인 것은 아닙니다. 실험과 해석은 구분합니다.

패치와 회귀 장면 보관하기

이동과 회전이 교환되지 않는 예를 남깁니다. 단위행렬만 쓰면 이 오류가 숨습니다. 최소 검사가 통과하면 일반 카메라 움직임과 대표 기하를 추가하고 같은 버전에서 비교합니다. 남는 별도 오류는 다른 항목으로 기록합니다.

자주 묻는 질문

스크린샷으로 정확한 원인을 아나요?

보통 현상과 위치를 줍니다. 코드·상태·재현으로 원인을 구별합니다.

컴파일 성공이면 수학도 맞나요?

문법이 유효해도 변환 순서가 틀릴 수 있습니다.

모든 패치를 같이 시험하나요?

한 번에 한 가설을 검사해야 결과 원인을 해석할 수 있습니다.

JavaScript로 GPU도 검증하나요?

명시된 계산만 검사합니다. 렌더와 호스트 검사는 별도입니다.

전체 저장소가 필요한가요?

재현 장면과 관련 상태로 시작해 가설에 필요한 의존을 추가합니다.

최종 버그 기록은 무엇인가요?

버전·입력·기대와 관측·실험·채택 패치·회귀 검사·불확실성입니다.

참고 자료

• Khronos 정점 변환.
• MDN 행렬 uniform.