3.3 기본: 오류 의심 구간 → glGetError 반복 조회
4.3 또는 KHR_debug: 지원 확인 → debug output 활성화
→ 콜백·필터 등록 → 객체 라벨·그룹 → 메시지 분류
셰이더 실패: 위와 별개로 compile/link status·log 조회

기본 오류 큐

// GL 3.3 Core, 현재 컨텍스트가 유효합니다.
for (GLenum error = glGetError(); error != GL_NO_ERROR; error = glGetError()) {
    std::fprintf(stderr, "GL error: 0x%x\n", error);
}

INVALID_ENUM은 허용되지 않는 열거값, INVALID_VALUE는 값 범위, INVALID_OPERATION은 현재 상태와 맞지 않는 사용을 먼저 봅니다. INVALID_FRAMEBUFFER_OPERATION은 FBO 상태, OUT_OF_MEMORY는 할당 문제를 확인합니다. 코드 줄 하나와 오류 하나가 항상 일대일로 기록되는 로그로 생각하지 않습니다. 원인 구간을 좁혀 조회합니다.

컨텍스트 없이 루프를 실행하지 않습니다. 오류가 발생하면 그 작업의 효과를 규격에 따라 판단해야 하며, 이후 모든 상태가 정상일 것이라고 가정하지 않습니다. 메모리 부족·reset 같은 상황은 단순 인수 오류와 다른 복구 정책이 필요합니다.

디버그 출력 설정

4.3 코어 또는 지원·로딩된 KHR_debug 경로에서 glEnable(GL_DEBUG_OUTPUT)과 glDebugMessageCallback을 사용합니다. 동기 콜백이 필요한 개발 상황에서는 GL_DEBUG_OUTPUT_SYNCHRONOUS를 켭니다. 동기화되지 않은 콜백은 다른 스레드나 나중 시점에 실행될 수 있으므로 GL 호출·공유 로그 접근을 무심코 넣지 않습니다.

glDebugMessageControl로 필요한 종류를 남기되 오류를 숨겨 깨끗한 로그를 만드는 것이 목적이 되어서는 안 됩니다. glObjectLabel과 push/pop debug group으로 버퍼·패스 이름을 붙이면 숫자 핸들보다 위치를 찾기 쉽습니다. 콜백에서 사용한 user pointer의 수명도 등록 기간보다 길어야 합니다.

콜백 선언과 등록

GLAD가 GL 4.3 또는 KHR_debug 진입점을 포함하고 실제 컨텍스트도 이를 지원하는 경우입니다. 선언은 GLAD 헤더와 <cstdio> 뒤에 둡니다. 아래 콜백은 GL을 다시 호출하지 않고 전달받은 메시지만 기록합니다.

void GLAD_API_PTR onDebug(GLenum source, GLenum type, GLuint id, GLenum severity,
                         GLsizei length, const GLchar* message, const void*) {
    std::fprintf(stderr, "GL id=%u source=0x%x type=0x%x severity=0x%x: ",
                 id, source, type, severity);
    if (length > 0) std::fwrite(message, 1, static_cast<std::size_t>(length), stderr);
    std::fputc('\n', stderr);
}

// 컨텍스트·함수 로딩 후, 렌더링 작업 전에 등록합니다.
glEnable(GL_DEBUG_OUTPUT);
glEnable(GL_DEBUG_OUTPUT_SYNCHRONOUS);
glDebugMessageCallback(onDebug, nullptr);

// 로그 수신이 더 필요 없으면 glDebugMessageCallback(nullptr, nullptr);

기본 3.3 전용 GLAD 생성 결과에는 이 API가 없을 수 있으므로 런타임 if만 추가하는 것으로 컴파일 조건을 해결하지 않습니다. 필요한 버전·확장을 로더에 생성해야 합니다. 동기 모드는 원인 호출을 찾기 쉽지만 비용을 늘릴 수 있어 운영 경로의 기본값으로 강제하지 않습니다.

버전과 환경

ARB_debug_output은 KHR_debug와 동일한 API 집합이 아닙니다. 함수 접미사와 지원 경로를 확인합니다. debug 컨텍스트 요청이 모든 플랫폼에서 그대로 적용되는 것도 아닙니다. 원격 구현처럼 콜백 전달이 제한되는 환경에서는 지원되는 메시지 로그 조회 경로를 확인합니다.

셰이더 문법 오류는 컴파일·링크 로그, 오류 없이 검게 나오는 장면은 출력 진단에서 구분합니다. 콘텐츠 예제에 항상 glGetError나 동기 디버그 콜백을 성능 비용 없이 넣어도 된다고 설명하지 않습니다.