NVIDIA publicou um guia sobre como o OptiX Toolkit (OTK) ajuda a depurar aplicações de ray tracing em GPU. O texto foca em duas facilidades da ferramenta: uma verificação consistente de códigos de erro das APIs OptiX e CUDA, e um mecanismo de debug device-side direcionado chamado DebugLocation. OTK está disponível no repositório NVIDIA/optix-toolkit e é distribuído sob uma licença BSD 3-clause–style.
Verificação unificada de erros
OTK oferece macros e funções inline que padronizam a checagem de retorno das APIs OptiX, CUDA runtime e CUDA driver. As macros fornecidas permitem políticas de tratamento, por exemplo OTK_ERROR_CHECK (lança exceção) e OTK_ERROR_CHECK_NOTHROW (imprime em std::cerr e continua). A implementação minimiza o uso de macros, delegando a lógica a funções inline onde é possível colocar breakpoints.
A mensagem diagnóstica gerada segue o formato: file(line): expr failed with error nnn (name): message. As funções auxiliares obtêm o nome simbólico e a mensagem legível da API correspondente, e os headers específicos do OTK especializam essas funções para cada API usada.
Debug device-side com DebugLocation
O header <OptiXToolkit/ShaderUtil/DebugLocation.h> fornece a estrutura DebugLocation com membros como enabled, dumpSuppressed, debugIndexSet e debugIndex. O mecanismo emite informação de debug quando estas condições se cumprem: enabled é true; dumpSuppressed é false; debugIndexSet é true; e o índice de lançamento atual bate com debugIndex. Inclua uma instância dessa estrutura nos parâmetros de launch para controlar interativamente a saída.
OTK expõe a função template debugInfoDump que recebe um callback com setColor e dump. setColor é usado para desenhar uma marca visual no pixel de depuração; dump imprime os dados relevantes para o índice selecionado. A marcação visual é descrita como um pixel vermelho dentro de uma borda preta e outra branca de um pixel, para facilitar identificação.
Há suporte a um modo one-shot para evitar um excesso de saída: habilita-se o DebugLocation, define-se dumpSuppressed e debugIndex, interage-se com a cena até o ponto de interesse, desativa-se dumpSuppressed para obter a saída naquele lançamento e, em seguida, reativa-se dumpSuppressed.
Exemplo e recomendações
O exemplo DemandPbrtScene no OTK demonstra o uso de DebugLocation com comportamento one-shot e integração com ImGui para seleção interativa da posição de depuração. O texto recomenda habilitar a validação do OptiX em builds de debug, envolver chamadas CUDA e OptiX com OTK_ERROR_CHECK e usar DebugLocation para isolar bugs do lado da GPU mais cedo no desenvolvimento.
Para começar, o OTK pode ser obtido no repositório NVIDIA/optix-toolkit. Por ser BSD 3-clause–style, o código pode ser copiado, adaptado e integrado a projetos OptiX conforme necessário.
Fonte: NVIDIA Developer Blog
