Q3DScene Class
Q3DScene 类提供了对正在可视化的 3D 场景的描述。更多内容...
| 头文件： | #include <Q3DScene> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Graphs) target_link_libraries(mytarget PRIVATE Qt6::Graphs) |
| qmake： | QT += graphs |
| 在 QML 中： | Scene3D |
| 继承自： | QObject |
- 所有成员列表（包括继承的成员）
- Q3DScene 属于Qt Graphs 3D C++ 类库。
属性
|
|
公共函数
| Q3DScene(QObject *parent = nullptr) | |
| virtual | ~Q3DScene() override |
| qreal | devicePixelRatio() const |
| QPoint | graphPositionQuery() const |
| QPoint | invalidSelectionPoint() const |
| bool | isPointInPrimarySubView(QPoint point) |
| bool | isPointInSecondarySubView(QPoint point) |
| bool | isSecondarySubviewOnTop() const |
| bool | isSlicingActive() const |
| QRect | primarySubViewport() const |
| QRect | secondarySubViewport() const |
| QPoint | selectionQueryPosition() const |
| void | setDevicePixelRatio(qreal pixelRatio) |
| void | setGraphPositionQuery(QPoint point) |
| void | setPrimarySubViewport(QRect primarySubViewport) |
| void | setSecondarySubViewport(QRect secondarySubViewport) |
| void | setSecondarySubviewOnTop(bool isSecondaryOnTop) |
| void | setSelectionQueryPosition(QPoint point) |
| void | setSlicingActive(bool isSlicing) |
| QRect | viewport() const |
信号
| void | devicePixelRatioChanged(qreal pixelRatio) |
| void | graphPositionQueryChanged(QPoint position) |
| void | primarySubViewportChanged(QRect subViewport) |
| void | secondarySubViewportChanged(QRect subViewport) |
| void | secondarySubviewOnTopChanged(bool isSecondaryOnTop) |
| void | selectionQueryPositionChanged(QPoint position) |
| void | slicingActiveChanged(bool isSlicingActive) |
| void | viewportChanged(QRect viewport) |
详细说明
该 3D 场景包含一个活动摄像机和一个活动光源。假设可视化数据位于固定位置。
该 3D 场景还会跟踪用于图渲染的视口、视口内用于显示主 3D 图视图的主子视口，以及用于显示数据 2D 切片视图的辅助子视口。 默认情况下，子视口的大小由Q3DScene 调整。若要覆盖此调整行为，需监听viewportChanged()和slicingActiveChanged()两个信号，并据此重新计算子视口大小。
此外，场景中还设有一个标志，用于跟踪辅助 2D 切片视图当前是否处于活动状态。
注意：并非 所有图形都支持辅助 2D 切片视图。
属性文档
devicePixelRatio : qreal
该属性存储在将输入坐标映射到像素坐标时所使用的设备像素比。
访问函数：
| qreal | devicePixelRatio() const |
| void | setDevicePixelRatio(qreal pixelRatio) |
通知信号：
| void | devicePixelRatioChanged(qreal pixelRatio) |
graphPositionQuery : QPoint
该属性存储用户输入的坐标，场景应将这些坐标作为图位置查询进行处理。
如果该属性设置为invalidSelectionPoint()以外的值，图形将尝试在主视口内将指定坐标与图形位置进行匹配。渲染过程完成后，该属性将恢复为默认状态invalidSelectionPoint()。在接下来的渲染过程之后，可从Q3DGraphsWidgetItem::queriedGraphPosition 属性中读取查询到的图形位置。
由于不存在与特定屏幕位置完全对应的唯一正确 3D 坐标，因此为了保持一致性，查询始终针对包围图表的不可见矩形框的内侧进行。
注意：条形图 仅允许在图表底部水平面进行位置查询。
访问函数：
| QPoint | graphPositionQuery() const |
| void | setGraphPositionQuery(QPoint point) |
通知器信号：
| void | graphPositionQueryChanged(QPoint position) |
另请参阅 Q3DGraphsWidgetItem::queriedGraphPosition 。
[read-only] invalidSelectionPoint : const QPoint
该属性包含一个点，该点表示一个无效的选择位置。
访问函数：
| QPoint | invalidSelectionPoint() const |
primarySubViewport : QRect
该属性存储了视口内当前子视口矩形，该视口是图表主视图的目标位置。
如果未显式设置主子视口，则其大小将为 `viewport()` 的五分之一。
注意：若将 primarySubViewport设置为 大于视口或超出视口范围，视口将相应地调整大小。
访问函数：
| QRect | primarySubViewport() const |
| void | setPrimarySubViewport(QRect primarySubViewport) |
通知器信号：
| void | primarySubViewportChanged(QRect subViewport) |
secondarySubViewport : QRect
该属性用于在视口内保存辅助视口矩形。
辅助视口用于在某些图中绘制 2D 切片视图。如果未显式设置，其大小将与视口大小相同。
注意：如果 次级子视口大于主视口或位于主视口之外，则主视口会相应地调整大小。
访问函数：
| QRect | secondarySubViewport() const |
| void | setSecondarySubViewport(QRect secondarySubViewport) |
通知信号：
| void | secondarySubViewportChanged(QRect subViewport) |
secondarySubviewOnTop : bool
该属性决定了是渲染 2D 切片视图还是 3D 视图在最上方。
访问函数：
| bool | isSecondarySubviewOnTop() const |
| void | setSecondarySubviewOnTop(bool isSecondaryOnTop) |
通知信号：
| void | secondarySubviewOnTopChanged(bool isSecondaryOnTop) |
selectionQueryPosition : QPoint
该属性存储用户输入的坐标，场景应将该坐标作为选区进行处理。
如果该属性设置为invalidSelectionPoint()以外的值，则图形将尝试在主视口内指定坐标处选择一个数据项、坐标轴标签或自定义项。渲染过程结束后，该属性将恢复为默认状态invalidSelectionPoint()。
访问函数：
| QPoint | selectionQueryPosition() const |
| void | setSelectionQueryPosition(QPoint point) |
通知器信号：
| void | selectionQueryPositionChanged(QPoint position) |
另请参阅 Q3DGraphsWidgetItem::selectedElement 。
slicingActive : bool
该属性表示 2D 切片视图当前是否处于活动状态。
如果true ，则Q3DGraphsWidgetItem::selectionMode 必须将QtGraphs3D::SelectionFlag::Row 或QtGraphs3D::SelectionFlag::Column 中的一个设置为有效的选择项。
注意：并非 所有图形都支持 2D 切片视图。
访问函数：
| bool | isSlicingActive() const |
| void | setSlicingActive(bool isSlicing) |
通知信号：
| void | slicingActiveChanged(bool isSlicingActive) |
[read-only] viewport : QRect
该属性包含一个只读属性，其中存储了当前视口矩形，所有 3D 渲染均以此为目标。
访问函数：
| QRect | viewport() const |
通知器信号：
| void | viewportChanged(QRect viewport) |
成员函数文档
[explicit] Q3DScene::Q3DScene(QObject *parent = nullptr)
构建一个包含一个光源和一个摄像机的基本场景。可以指定可选的parent 参数，该参数随后将传递给QObject 构造函数。
[override virtual noexcept] Q3DScene::~Q3DScene()
删除该3D场景及其所包含的所有对象。
QPoint Q3DScene::invalidSelectionPoint() const
返回一个表示选择位置无效的QPoint 。
注意： 这是 invalidSelectionPoint 属性的获取 函数。
bool Q3DScene::isPointInPrimarySubView(QPoint point)
返回指定point 是否位于主子视图内部。如果该点位于主子视图内部，则返回true 。
注意：如果 子视图重叠，且给定的point 位于两个子视图内部，则只有当主子视图位于最上层时，结果才为true 。
bool Q3DScene::isPointInSecondarySubView(QPoint point)
返回指定point 是否位于二级子视图内。如果该点位于二级子视图内，则返回true 。
注意：如果 子视图重叠，且给定的point 同时位于两个子视图内，则只有当次要子视图位于最上方时，结果才为true 。
© 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.
