Qt 3D 将渲染迁移至 RHI

请注意，在 Qt 6 中，Qt 3D 将默认使用其 RHI 渲染后端。

仍然可以使用 Qt 5 系列中的旧版 Qt OpenGL 后端。可通过将环境变量 QT3D_RENDERER 设置为 opengl 来启用此功能。如果您不希望将应用程序移植以支持 RHI，或者需要 RHI 后端目前受限或无法提供的功能，则必须进行此设置。

目前，已知的 RHI 限制包括：

无法显式进行位图复制（必须通过将四边形渲染到帧缓冲区来手动复制）
无法显式设置 MemoryBarrier
并非所有纹理格式均可用
目前不支持间接绘制
目前不支持几何着色器。
不同的 RHI 后端可能支持不同的功能集。

此外，请注意不要将Qt 3D 的 OpenGL 渲染后端与运行在 OpenGL 之上的Qt 3D 的 RHI 渲染后端混淆。

RHI是对不同图形API的一种抽象。这意味着在给定的平台上，多个RHI实例可以使用不同的后端。

若要强制 RHI 使用指定的后端，应将 QSG_RHI_BACKEND 环境变量设置为 opengl、vulkan、metal 或 directx 之一。

添加兼容 RHI 的技术

要为Qt 3D 材质/特效添加RHI支持，需要创建一个针对RHI的新技术。截至本文撰写之时，唯一有效的RHI版本是1.0。

Material {
    Effect {
        techniques: [
            Technique {
                id: gl3Technique
                graphicsApiFilter {
                    api: GraphicsApiFilter.OpenGL
                    profile: GraphicsApiFilter.CoreProfile
                    majorVersion: 3
                    minorVersion: 1
                }
                renderPasses: RenderPass {
                    id: gl3Pass
                    shaderProgram: ShaderProgram {
                        ...
                    }
                }
            },
            Technique {
                id: rhiTechnique
                graphicsApiFilter {
                    api: GraphicsApiFilter.RHI
                    profile: GraphicsApiFilter.NoProfile
                    majorVersion: 1
                    minorVersion: 0
                }
                renderPasses: RenderPass {
                    id: rhiPass
                    shaderProgram: ShaderProgram {
                        ...
                    }
                }
            }
        ]
    }
}

QMaterial *material = new QMaterial();
QEffect *effect = new QEffect();

// Set the effect on the material
material->setEffect(effect);

{
    QTechnique *gl3Technique = new QTechnique();
    QRenderPass *gl3Pass = new QRenderPass();
    QShaderProgram *glShader = new QShaderProgram();

    // Set the shader on the render pass
    gl3Pass->setShaderProgram(glShader);

    // Add the pass to the technique
    gl3Technique->addRenderPass(gl3Pass);

    // Set the targeted GL version for the technique
    gl3Technique->graphicsApiFilter()->setApi(QGraphicsApiFilter::OpenGL);
    gl3Technique->graphicsApiFilter()->setMajorVersion(3);
    gl3Technique->graphicsApiFilter()->setMinorVersion(1);
    gl3Technique->graphicsApiFilter()->setProfile(QGraphicsApiFilter::CoreProfile);

    // Add the technique to the effect
    effect->addTechnique(gl3Technique);
}

{
    QTechnique *rhiTechnique = new QTechnique();
    QRenderPass *rhiPass = new QRenderPass();
    QShaderProgram *rhiShader = new QShaderProgram();

    // Set the shader on the render pass
    rhiPass->setShaderProgram(glShader);

    // Add the pass to the technique
    rhiTechnique->addRenderPass(rhiPass);

    // Set the targeted RHI version for the technique
    rhiTechnique->graphicsApiFilter()->setApi(QGraphicsApiFilter::RHI);
    rhiTechnique->graphicsApiFilter()->setMajorVersion(1);
    rhiTechnique->graphicsApiFilter()->setMinorVersion(0);
    rhiTechnique->graphicsApiFilter()->setProfile(QGraphicsApiFilter::NoProfile);

    // Add the technique to the effect
    effect->addTechnique(rhiTechnique);
}

创建兼容 RHI 的着色器

无论 RHI 运行在何种后端之上，着色器均应采用 GLSL 450 编写。

与早期 GLSL 版本相比，变更非常少，主要差异体现在 uniform 的声明方式上。另请注意，输入和输出变量的位置必须明确定义，并且在各个着色器阶段之间应保持一致。

#version 450 core

layout(location = 0) in vec3 vertexPosition;
layout(location = 0) out vec3 worldPosition;

layout(std140, binding = 0) uniform qt3d_render_view_uniforms {
  mat4 viewMatrix;
  mat4 projectionMatrix;
  mat4 uncorrectedProjectionMatrix;
  mat4 clipCorrectionMatrix;
  mat4 viewProjectionMatrix;
  mat4 inverseViewMatrix;
  mat4 inverseProjectionMatrix;
  mat4 inverseViewProjectionMatrix;
  mat4 viewportMatrix;
  mat4 inverseViewportMatrix;
  vec4 textureTransformMatrix;
  vec3 eyePosition;
  float aspectRatio;
  float gamma;
  float exposure;
  float time;
  float yUpInNDC;
  float yUpInFBO;
};

layout(std140, binding = 1) uniform qt3d_command_uniforms {
  mat4 modelMatrix;
  mat4 inverseModelMatrix;
  mat4 modelViewMatrix;
  mat3 modelNormalMatrix;
  mat4 inverseModelViewMatrix;
  mat4 modelViewProjection;
  mat4 inverseModelViewProjectionMatrix;
};

void main()
{
    ...
}

有关着色器变更的更多详情，请参阅Qt3DRender::QShaderProgram

Qt 3D 扩展功能

Qt 3D 中的材质相关扩展功能已移植到RHI中。

概述渲染帧图

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.