使用QOpenGLWidget无法显示纹理仅显示黑框的问题求助

问题描述 #

刚接触QOpenGLWidget，将QImage传入自定义QOpenGLWidget后控件仅显示黑框，已尝试修改QImage格式、直接传入原始数据到纹理，问题仍未解决。配置为：在Qt Designer中使用QWidget作为自定义QOpenGLWidget的父控件。

原始代码 #

#include "OpenGLWidget.h"

OpenGLWidget::OpenGLWidget(QWidget* parent) : QOpenGLWidget(parent) 
{
    setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Fixed);
    setFixedSize(500, 500);
}

OpenGLWidget::~OpenGLWidget()
{
    makeCurrent();
    delete m_texture;
    doneCurrent();
}

void OpenGLWidget::initializeGL()
{
    initializeOpenGLFunctions();

    // Enable texture mapping
    glEnable(GL_TEXTURE_2D);

    // Create an OpenGL texture object
    m_texture = new QOpenGLTexture(QOpenGLTexture::Target2D);
    m_texture->setMinificationFilter(QOpenGLTexture::Nearest);
    m_texture->setMagnificationFilter(QOpenGLTexture::Nearest);
    m_texture->setWrapMode(QOpenGLTexture::ClampToEdge);
    m_texture->create();
    if (m_texture != nullptr && m_texture->isCreated())
    {
        // Create and compile shaders
        shaderProgram.addShaderFromSourceCode(QOpenGLShader::Vertex,
            "#version 330\n"
            "in vec2 vertexPosition;"
            "in vec2 vertexTexCoord;"
            "out vec2 texCoord;"
            "void main() {"
            "    gl_Position = vec4(vertexPosition, 0.0, 1.0);"
            "    texCoord = vertexTexCoord;"
            "}");

        shaderProgram.addShaderFromSourceCode(QOpenGLShader::Fragment,
            "#version 330\n"
            "in vec2 texCoord;"
            "uniform sampler2D textureSampler;"
            "out vec4 fragColor;"
            "void main() {"
            "    fragColor = texture(textureSampler, texCoord);"
            "}");

        // Create vertex buffer
        GLfloat vertices[] = {
            -1.0f, -1.0f, 0.0f, 0.0f,
             1.0f, -1.0f, 1.0f, 0.0f,
             1.0f,  1.0f, 1.0f, 1.0f,
            -1.0f,  1.0f, 0.0f, 1.0f
        };

        vertexBuffer.create();
        vertexBuffer.bind();
        vertexBuffer.allocate(vertices, sizeof(vertices));

        // Create vertex array object
        vertexArrayObject.create();
        vertexArrayObject.bind();

        shaderProgram.enableAttributeArray("vertexPosition");
        shaderProgram.enableAttributeArray("vertexTexCoord");
        shaderProgram.setAttributeBuffer("vertexPosition", GL_FLOAT, 0, 2, sizeof(GLfloat) * 4);
        shaderProgram.setAttributeBuffer("vertexTexCoord", GL_FLOAT, sizeof(GLfloat) * 2, 2, sizeof(GLfloat) * 4);
    }
}

void OpenGLWidget::resizeGL(int w, int h)
{
    glViewport(0, 0, w, h);
}

void OpenGLWidget::paintGL()
{
    // Clear the buffer
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    // Load image data into the OpenGL texture
    if (!m_image.isNull())
    {
        m_texture->setData(m_image);
    }

    // Use shader program
    if (shaderProgram.bind())
    {
        // Bind texture
        m_texture->bind();

        // Draw quad
        vertexArrayObject.bind();
        glDrawArrays(GL_TRIANGLE_FAN, 0, 4);
        vertexArrayObject.release();

        // Unbind texture
        m_texture->release();

        // Release shader program
        shaderProgram.release();
    }
}

void OpenGLWidget::setImage(QImage image)
{
    m_image = image;
}

核心问题与修复方案 #

1. Shader程序未链接 #

原始代码仅添加了着色器源码，但未调用shaderProgram.link()，导致Shader程序无法生效，这是黑框的核心原因。

修复：在添加完顶点和片段着色器后，添加链接代码并检查错误：

if (!shaderProgram.link()) {
    qDebug() << "Shader链接失败:" << shaderProgram.log();
    return;
}

2. QImage格式与坐标系不兼容 #

QImage默认格式可能不被OpenGL支持，且QImage的Y轴方向与OpenGL纹理相反，会导致图片显示异常或黑框。

修复：在setImage中转换为OpenGL兼容格式并镜像：

void OpenGLWidget::setImage(QImage image)
{
    if (image.isNull()) return;
    // 转换为RGBA8888格式（OpenGL原生支持）并镜像Y轴
    m_image = image.convertToFormat(QImage::Format_RGBA8888).mirrored();
    makeCurrent();
    m_texture->setData(m_image);
    doneCurrent();
    update(); // 触发控件重绘
}

3. PaintGL中重复上传纹理数据 #

每次重绘都调用m_texture->setData(m_image)会重复上传数据，浪费性能且可能导致异常，应仅在图片更新时上传。

修复：将纹理数据上传逻辑移到setImage中，paintGL只负责绘制。

4. 显式设置纹理采样器单元 #

Shader中的uniform sampler2D默认绑定纹理单元0，但显式设置可避免潜在的绑定错误。

修复：在Shader绑定后添加：

shaderProgram.setUniformValue("textureSampler", 0);

5. 添加错误检查 #

在关键步骤添加错误检查，便于定位问题：

• Shader编译、链接后检查日志
• 纹理创建后检查是否成功
• OpenGL调用后可通过glGetError()检查错误

修改后的完整关键代码片段 #

void OpenGLWidget::initializeGL()
{
    initializeOpenGLFunctions();

    glEnable(GL_TEXTURE_2D);
    glClearColor(0.0f, 0.0f, 0.0f, 1.0f); // 显式设置清屏颜色

    m_texture = new QOpenGLTexture(QOpenGLTexture::Target2D);
    m_texture->setMinificationFilter(QOpenGLTexture::Nearest);
    m_texture->setMagnificationFilter(QOpenGLTexture::Nearest);
    m_texture->setWrapMode(QOpenGLTexture::ClampToEdge);
    m_texture->create();

    if (m_texture && m_texture->isCreated())
    {
        // 添加顶点和片段着色器代码（与原始一致）

        // 链接Shader并检查错误
        if (!shaderProgram.link()) {
            qDebug() << "Shader链接失败:" << shaderProgram.log();
            return;
        }

        // VBO和VAO配置（与原始一致）
    }
}

void OpenGLWidget::paintGL()
{
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    if (shaderProgram.bind())
    {
        shaderProgram.setUniformValue("textureSampler", 0);
        m_texture->bind();
        vertexArrayObject.bind();
        glDrawArrays(GL_TRIANGLE_FAN, 0, 4);
        vertexArrayObject.release();
        m_texture->release();
        shaderProgram.release();
    }
}

void OpenGLWidget::setImage(QImage image)
{
    if (image.isNull()) return;
    m_image = image.convertToFormat(QImage::Format_RGBA8888).mirrored();
    makeCurrent();
    m_texture->setData(m_image);
    doneCurrent();
    update();
}

内容的提问来源于stack exchange，提问作者sean