QOpenGLDebugLogger Class

상세 설명

서론

OpenGL 프로그래밍은 오류가 발생하기 매우 쉽습니다. 대부분의 경우, OpenGL 호출 중 단 한 번의 오류만으로도 애플리케이션의 전체 구역이 작동하지 않게 되어 화면에 아무것도 표시되지 않을 수 있습니다.

OpenGL 구현에서 오류가 반환되지 않았음을 확실히 확인하는 유일한 방법은 모든 API 호출 후마다 ` glGetError `를 통해 확인하는 것입니다. 게다가 OpenGL 오류는 누적되므로, `glGetError`는 항상 다음과 같은 루프 내에서 사용해야 합니다:

GLenum error = GL_NO_ERROR;
do {
    error = glGetError();
    if (error != GL_NO_ERROR) {
        // handle the error
    }
} while (error != GL_NO_ERROR);

오류 스택을 지우려고 할 때는, GL_NO_ERROR가 반환될 때까지 계속 진행하는 것뿐만 아니라, GL_CONTEXT_LOST가 반환되면 루프를 중단해야 합니다. 이 오류 값은 반복적으로 발생하기 때문입니다.

(애플리케이션 개발자로서) 우리가 관심을 갖는 다른 정보들도 많이 있습니다. 예를 들어 성능 문제나 더 이상 사용되지 않는 API 사용에 대한 경고 등이 있습니다. 이러한 종류의 메시지는 일반적인 OpenGL 오류 보고 메커니즘을 통해 보고되지 않습니다.

QOpenGLDebugLogger는 OpenGL 디버그 로그에 대한 접근을 제공함으로써 이러한 문제들을 해결하는 것을 목표로 합니다. 사용 중인 OpenGL 구현체가 이를 지원한다면( GL_KHR_debug 확장을 노출함으로써), OpenGL 서버에서 발생하는 메시지는 내부 OpenGL 로그에 기록되거나, OpenGL에서 생성되는 즉시 “실시간”으로 리스너에게 전달됩니다.

QOpenGLDebugLogger는 이 두 가지 작동 모드를 모두 지원합니다. 두 모드의 차이점에 대해서는 다음 섹션을 참조하십시오.

OpenGL 디버그 컨텍스트 생성

효율성상의 이유로, OpenGL 컨텍스트가 디버그 컨텍스트가 아닌 한 OpenGL 구현체는 디버그 출력을 전혀 생성하지 않아도 됩니다. Qt OpenGL에서 디버그 컨텍스트를 생성하려면, ` QOpenGLContext ` 객체를 생성하는 데 사용되는 ` QSurfaceFormat `에 ` QSurfaceFormat::DebugContext ` 형식 옵션을 설정해야 합니다:

QSurfaceFormat format;
// asks for a OpenGL 3.2 debug context using the Core profile
format.setMajorVersion(3);
format.setMinorVersion(2);
format.setProfile(QSurfaceFormat::CoreProfile);
format.setOption(QSurfaceFormat::DebugContext);

QOpenGLContext *context = new QOpenGLContext;
context->setFormat(format);
context->create();

3.2 OpenGL Core Profile을 요청하는 것은 단지 예제의 목적을 위한 것일 뿐이라는 점에 유의하십시오. 이 클래스는 GL_KHR_debug 확장 기능의 사용 가능 여부에 의존하기 때문에(아래 참조), 특정 OpenGL 또는 OpenGL ES 버전에 묶여 있지 않습니다.

QOpenGLDebugLogger 생성 및 초기화

Qt OpenGL Debug Logger는 QObject 에서 파생된 간단한 클래스입니다. 모든 QObject 하위 클래스와 마찬가지로 인스턴스를 생성하고(선택적으로 부모 객체를 지정할 수 있음), Qt OpenGL 함수와 마찬가지로 현재 OpenGL 컨텍스트가 존재하는 상태에서 initialize()를 호출하여 사용 전에 초기화해야 합니다:

QOpenGLContext *ctx = QOpenGLContext::currentContext();
QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this);

logger->initialize(); // initializes in the current context, i.e. ctx

OpenGL에서 기록된 메시지에 접근하려면 컨텍스트에서 GL_KHR_debug 확장이 사용 가능해야 한다는 점에 유의하십시오. 다음 호출을 통해 이 확장의 존재 여부를 확인할 수 있습니다:

ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug"));

여기서 ctx 는 유효한 QOpenGLContext 입니다. 확장 기능이 지원되지 않는 경우, initialize()는 false를 반환합니다.

내부 OpenGL 디버그 로그 읽기

OpenGL 구현체는 디버그 메시지에 대한 내부 로그를 유지합니다. 이 로그에 저장된 메시지는 loggedMessages() 함수를 사용하여 가져올 수 있습니다:

const QList<QOpenGLDebugMessage> messages = logger->loggedMessages();
for (const QOpenGLDebugMessage&message: messages)
    qDebug() << message;

내부 로그의 용량은 제한되어 있으며, 용량이 가득 차면 새로 들어오는 메시지를 저장할 공간을 확보하기 위해 오래된 메시지가 삭제됩니다. ` loggedMessages()`를 호출하면 내부 로그도 비워집니다.

디버그 메시지를 하나도 놓치지 않으려면 이 함수를 호출하는 대신 실시간 로깅을 사용해야 합니다. 하지만 컨텍스트 생성 시점과 실시간 로깅이 활성화되기 전의 시간대(또는 일반적으로 실시간 로깅이 비활성화된 상태)에는 여전히 디버그 메시지가 생성될 수 있습니다.

메시지의 실시간 로깅

구현에서 디버그 메시지가 생성되는 즉시 OpenGL 서버로부터 해당 메시지 스트림을 수신할 수도 있습니다. 이를 위해서는 적절한 슬롯을 messageLogged() 신호에 연결하고, startLogging()를 호출하여 로깅을 시작해야 합니다:

connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage);
logger->startLogging();

마찬가지로, stopLogging() 함수를 호출하여 언제든지 로깅을 비활성화할 수 있습니다.

실시간 로깅은 startLogging()에 전달되는 매개변수에 따라 비동기 또는 동기 방식으로 수행될 수 있습니다. 비동기 모드(오버헤드가 매우 적기 때문에 기본값)로 로깅할 경우, OpenGL 구현체는 언제든지 메시지를 생성할 수 있으며, 해당 메시지가 로깅되도록 유발한 OpenGL 명령어의 순서와 다른 순서로 메시지를 생성할 수도 있습니다. 또한 메시지는 컨텍스트가 현재 바인딩된 스레드와 다른 스레드에서 생성될 수도 있습니다. 이는 OpenGL 구현체가 대개 다중 스레드 방식이며 비동기적이기 때문이며, 따라서 디버그 메시지의 상대적 순서와 타이밍에 대해서는 어떠한 보증도 하지 않습니다.

반면, 동기 모드에서 로깅하는 것은 오버헤드가 크지만, OpenGL 구현체는 특정 명령어로 인해 발생한 모든 메시지가 명령어가 반환되기 전에 순서대로, 그리고 OpenGL 컨텍스트가 바인딩된 것과 동일한 스레드에서 수신되도록 보장합니다.

즉, 동기 모드에서 로깅을 수행하면 디버거에서 OpenGL 애플리케이션을 실행하고, ` messageLogged()` 신호에 연결된 슬롯에 중단점을 설정한 후, 백트레이스에서 로깅된 메시지를 발생시킨 정확한 호출을 확인할 수 있습니다. 이는 OpenGL 문제를 디버깅하는 데 매우 유용할 수 있습니다. 단, OpenGL 렌더링이 다른 스레드에서 수행되는 경우, 실제 백트레이스를 확인하려면 신호/슬롯 연결 유형을 ` Qt::DirectConnection `으로 강제 설정해야 합니다.

로깅 모드에 대한 자세한 내용은 LoggingMode 열거형 문서를 참조하십시오.

디버그 로그에 메시지 삽입

애플리케이션과 라이브러리는 디버그 로그에 사용자 정의 메시지를 삽입할 수 있습니다. 예를 들어, 관련 OpenGL 명령어 그룹을 표시하여 해당 명령어에서 발생하는 메시지를 나중에 식별할 수 있도록 하는 경우입니다.

이를 위해 createApplicationMessage() 또는 createThirdPartyMessage()를 호출하여 ` QOpenGLDebugMessage ` 객체를 생성한 다음, logMessage()를 호출하여 로그에 삽입할 수 있습니다:

QOpenGLDebugMessage message =
    QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message"));

logger->logMessage(message);

OpenGL 구현체마다 디버그 로그에 삽입할 수 있는 메시지의 길이에 대해 벤더별 제한이 있다는 점에 유의하십시오. 이 길이는 maximumMessageLength() 메서드를 호출하여 확인할 수 있으며, 제한 길이를 초과하는 메시지는 자동으로 잘립니다.

디버그 출력 제어

QOpenGLDebugMessage 또한 디버그 메시지에 필터를 적용하여 로깅되는 메시지의 양을 제한할 수 있습니다. enableMessages()을 호출하여 메시지 로깅을 활성화하고, disableMessages()을 호출하여 비활성화할 수 있습니다. 기본적으로 모든 메시지가 로깅됩니다.

다음과 같은 기준으로 메시지를 선택하여 활성화하거나 비활성화할 수 있습니다:

• 출처, 유형 및 심각도(선택 범위에 모든 ID 포함);
• ID, 소스 및 유형(선택 범위에 모든 심각도 포함);

특정 메시지에 대한 "활성화" 상태는 (id, source, type, severity) 튜플의 속성이며, 메시지 속성들은 어떠한 형태의 계층 구조도 형성하지 않는다는 점에 유의하십시오. enableMessages() 및 disableMessages() 호출 순서에 주의해야 합니다. 호출 순서에 따라 활성화/비활성화되는 메시지가 달라지기 때문입니다.

메시지 본문 자체를 기준으로 필터링하는 것은 불가능하며, 애플리케이션에서 직접 처리해야 합니다( messageLogged() 신호에 연결된 슬롯에서, 또는 loggedMessages()를 통해 내부 디버그 로그의 메시지를 가져온 후).

활성화/비활성화 상태 관리를 단순화하기 위해, QOpenGLDebugMessage 는 debug groups 개념도 지원합니다. 디버그 그룹은 디버그 메시지의 활성화/비활성화 구성 그룹을 포함합니다. 또한, 디버그 그룹은 스택 형태로 구성됩니다. 즉, pushGroup()을 호출하여 그룹을 푸시하고, popGroup()을 호출하여 그룹을 팝할 수 있습니다. (OpenGL 컨텍스트가 생성되면 스택에 이미 하나의 그룹이 존재합니다).

enableMessages() 및 disableMessages() 함수는 현재 디버그 그룹, 즉 디버그 그룹 스택의 최상단에 있는 그룹의 구성을 수정합니다.

새로운 그룹이 디버그 그룹 스택에 푸시되면, 해당 그룹은 이전에 스택의 최상위에 있던 그룹의 구성을 상속받습니다. 반대로, 디버그 그룹을 팝하면 새로운 최상위가 되는 디버그 그룹의 구성이 복원됩니다.

디버그 그룹을 스택에 추가(또는 제거)하면 QOpenGLDebugMessage::GroupPushType (또는 GroupPopType) 유형의 디버그 메시지가 자동으로 생성됩니다.