如何将嵌入QWidget的Qt3DWindow视图渲染保存为图片？

阿华AIGC实验室

2026-4-15

嘿，我太懂你折腾一整天却搞不定的挫败感了——明明Qt3D视图显示正常，却连个截图都搞不定，说出来都不信对吧？其实问题出在Qt3D的异步渲染机制上，你之前试的方法要么没适配这个机制，要么步骤没做全。我帮你调整代码，用Qt3D官方推荐的QRenderCapture来实现，肯定能成。

核心问题说明

Qt3D的渲染是在独立线程完成的，普通的grab()方法没法正确捕获3D渲染帧；而QRenderCapture是专门为Qt3D设计的截图工具，它能向渲染线程发送截图请求，等渲染完成后再返回结果——这也是你之前可能没处理好的点：没等渲染完成就去拿图片，自然拿不到。

修改后的完整代码

我在你的代码基础上添加了必要的截图逻辑，标记了新增的部分：

import sys
from PyQt6.QtWidgets import QApplication, QHBoxLayout, QWidget, QPushButton, QMainWindow
from PyQt6.QtGui import QIcon, QPixmap, QPainter, QImage, QMatrix4x4, QQuaternion, QVector3D, QColor, QGuiApplication
from PyQt6.QtCore import QTimer
from PyQt6.Qt3DCore import QEntity, QTransform
from PyQt6 import Qt3DRender
from PyQt6.Qt3DExtras import QForwardRenderer, QPhongMaterial, Qt3DWindow, QOrbitCameraController, QDiffuseSpecularMaterial, QTextureMaterial, QNormalDiffuseMapMaterial, QDiffuseMapMaterial 
from PyQt6.Qt3DExtras import QSphereMesh
from PyQt6.Qt3DRender import QRenderCapture, QRenderCaptureReply

class MainWindow(QMainWindow):
    def __init__(self):
        super(MainWindow, self).__init__()
        self.view = Qt3DWindow()
        self.container = QWidget.createWindowContainer(self.view)
        self.setCentralWidget(self.container)

        # Create & set layouts
        main_layout = QHBoxLayout()
        main_layout.addWidget(self.container)
        
        main_widget = QWidget()
        main_widget.setLayout(main_layout)
        self.setCentralWidget(main_widget)
       
        # Root entity
        self.rootEntity = QEntity()

        # Load mesh
        sphere_mesh = QSphereMesh()
        sphere_mesh.setRadius(20)

        mesh_entity = QEntity(self.rootEntity)
        mesh_entity.addComponent(sphere_mesh)
        
        # Load/create textures
        diffuse_material = QPhongMaterial(self.rootEntity)
        diffuse_material.setDiffuse(QColor.fromRgbF(0.1, 0.9, 0.7, 0.6))
        mesh_entity.addComponent(diffuse_material)

        # Camera
        self.camera = self.view.camera()
        self.camera.lens().setPerspectiveProjection(60.0, 16.0 / 9.0, 1, 1000.0)
        self.camera.setPosition(QVector3D(0.0, 0, 120.0))
        self.camera.setViewCenter(QVector3D(0.0, 0.0, 0.0))
        
        # camera controls
        self.camController = QOrbitCameraController(self.rootEntity)
        self.camController.setLinearSpeed(200.0)
        self.camController.setLookSpeed(280.0)
        self.camController.setCamera(self.camera)
        
        # Light
        light_entity = QEntity(self.rootEntity)
        light = Qt3DRender.QPointLight(light_entity)
        light.setConstantAttenuation(0)
        light_entity.addComponent(light)
        light_transform = QTransform()
        light_transform.setTranslation(QVector3D(350, 100, 200))
        light_entity.addComponent(light_transform)
        
        self.view.setRootEntity(self.rootEntity)

        # ------------------- 新增：初始化RenderCapture组件 -------------------
        self.render_capture = Qt3DRender.QRenderCapture()
        self.view.activeRenderer().addComponent(self.render_capture)
        # -------------------------------------------------------------------

        self.capture_btn = QPushButton('Capture', self)
        self.capture_btn.clicked.connect(self.capture_image)
        main_layout.addWidget(self.capture_btn)

    def capture_image(self):
        # ------------------- 新增：发送截图请求 -------------------
        # 创建截图请求对象
        capture_request = Qt3DRender.QRenderCaptureRequest()
        # 发送请求，获取异步回复对象
        reply = self.render_capture.requestCapture(capture_request)
        # 连接回复完成信号到处理函数
        reply.completed.connect(lambda: self.on_capture_completed(reply))
        # --------------------------------------------------------

    # ------------------- 新增：截图完成后的处理函数 -------------------
    def on_capture_completed(self, reply):
        # 获取渲染好的图片
        capture_image = reply.image()
        # 保存图片，可自行修改路径和格式（支持png/jpg等）
        if capture_image.save("qt3d_sphere_capture.png"):
            print("截图已成功保存！")
        else:
            print("保存失败，请检查路径是否有权限")
        # 记得释放回复对象的资源
        reply.deleteLater()
        # -------------------------------------------------------------

if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    window.setGeometry(100, 100, 800, 600)
    window.setWindowTitle("3D Object Viewer")
    window.show()
    sys.exit(app.exec())

关键步骤解释

初始化QRenderCapture：必须把这个组件添加到Qt3DWindow的活跃渲染器上，这样才能监听渲染线程的帧数据。
发送异步截图请求：调用requestCapture()后，会立刻返回一个QRenderCaptureReply对象，但此时图片还没生成——因为渲染线程还在处理。
监听完成信号：当渲染线程完成截图后，reply会发出completed信号，这时才能安全地获取图片并保存。
释放资源：处理完截图后，一定要调用reply.deleteLater()来释放内存，避免泄漏。