图形渲染与 Shader / 系统课时
排查黑屏问题
排查黑屏问题
OpenGL 黑屏通常不是“某一个 API 坏了”,而是渲染链路某处没有产出可见像素。本篇给出从窗口与清屏、着色器、顶点输入到绘制状态的固定排查顺序,目标是用最少改动把问题缩小到一个环节。
学习目标
- 能按渲染链路逐层确认黑屏发生在哪个阶段
- 能用诊断代码检查程序、VAO 和 OpenGL 错误状态
- 能识别视口、裁剪、深度、背面剔除和绘制参数导致的“有数据但看不见”
从显示链路定位断点
不要一上来同时改着色器、顶点数据和相机矩阵。先把“能否显示清屏色”作为第一条分界线:如果连清屏色都看不到,优先检查窗口、上下文、视口和交换缓冲;如果清屏色正常,再进入着色器、顶点输入和绘制阶段。

最有效的办法是一次只验证一个节点。每通过一层,就把它从怀疑列表中移除,而不是靠随机改参数碰运气。
先确认窗口、视口和清屏
先把场景渲染全部暂时移除,只保留清屏和交换缓冲。若窗口能稳定显示醒目的洋红色,说明窗口、OpenGL 上下文、主循环和前后缓冲交换基本正常。
// 片段示例:依赖已经创建并设为 current 的 GLFW/OpenGL 上下文。
int width = 0;
int height = 0;
glfwGetFramebufferSize(window, &width, &height);
// 视口必须使用 framebuffer 尺寸,高 DPI 屏幕上它可能不同于窗口逻辑尺寸。
glViewport(0, 0, width, height);
glClearColor(1.0f, 0.0f, 1.0f, 1.0f);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
glfwSwapBuffers(window);预期结果
窗口客户区显示稳定的洋红色;实际窗口尺寸可能不同。如果仍是黑色,重点检查 glfwMakeContextCurrent 是否作用于当前窗口、glfwSwapBuffers 是否每帧执行、framebuffer 的宽高是否为 0,以及窗口最小化或尚未收到有效尺寸回调的情况。视口宽高为 0 时,后续绘制即使执行也不会覆盖任何像素。
验证着色器和顶点输入
清屏正常后,把片元着色器暂时改成固定亮色,并让顶点着色器只使用最基础的位置输入。这样可以绕开纹理、光照和材质,把问题集中在“程序是否链接成功”和“顶点是否真的送进流水线”。
下面的诊断函数属于片段示例,依赖已有 OpenGL 上下文以及待检查的着色器程序。它不会修复问题,但能快速发现未链接程序、未绑定 VAO 或遗留错误。
#include <cstdio>
#include <glad/glad.h>
void printDrawDiagnostics(GLuint program) {
GLint linked = GL_FALSE;
GLint vao = 0;
glGetProgramiv(program, GL_LINK_STATUS, &linked);
glGetIntegerv(GL_VERTEX_ARRAY_BINDING, &vao);
GLenum error = glGetError();
std::printf("program=%u linked=%d\\n", program, linked);
std::printf("vao=%d bound=%s\\n", vao, vao == 0 ? "no" : "yes");
std::printf("glGetError=0x%04X\\n", error);
}预期输出
program=<ID> linked=1
vao=<ID> bound=yes
glGetError=0x0000<ID> 会随运行变化。若 linked=0,立即读取 program info log;若 bound=no,检查绘制前是否绑定了正确 VAO。还要确认 glVertexAttribPointer 的分量数、类型、步长和偏移与实际顶点结构一致,并且对应 attribute 已通过 glEnableVertexAttribArray 启用。
核对绘制参数和裁剪状态
当着色器、VAO 和缓冲都正常时,黑屏常由绘制调用或固定功能状态造成。glDrawArrays 的 count 必须是顶点数量;glDrawElements 的 count 是索引数量,type 必须与 EBO 中索引类型一致,最后一个参数是索引缓冲内的字节偏移。
排查时可以临时关闭容易“把所有东西都过滤掉”的状态,再逐项恢复。
// 片段示例:仅用于定位,不建议把这些状态长期写死。
glDisable(GL_CULL_FACE);
glDisable(GL_DEPTH_TEST);
glDisable(GL_SCISSOR_TEST);
glUseProgram(program);
glBindVertexArray(vao);
glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, nullptr);预期结果
若几何数据、着色器和索引正确,模型应以固定测试颜色出现在视口中。如果这样能看到模型,再逐个恢复深度测试、背面剔除和 Scissor。恢复背面剔除后消失,检查顶点绕序与 glFrontFace;恢复深度测试后消失,检查深度缓冲是否创建、每帧是否清除,以及投影矩阵的 near/far 是否合理;启用 Scissor 后消失,检查裁剪矩形是否覆盖当前视口。
固定顺序应当是:先证明 framebuffer 能显示清屏色,再证明着色器和顶点输入有效,最后检查绘制参数与裁剪状态。这样黑屏会从一个模糊现象变成某个明确阶段的失败。