Qt3DRender::QCamera Class
class Qt3DRender::QCameraQCamera 类定义了一个用于渲染场景的视点。更多内容...
| 头文件： | #include <Qt3DRender/QCamera> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS 3drender) target_link_libraries(mytarget PRIVATE Qt6::3drender) |
| qmake： | QT += 3drender |
| 在 QML 中： | Camera |
| 继承自： | Qt3DCore::QEntity |
| 状态： | 已弃用 |
该类已弃用。我们强烈建议不要在新代码中使用它。
公共类型
| enum | CameraTranslationOption { TranslateViewCenter, DontTranslateViewCenter } |
属性
|
|
公共函数
| QCamera(Qt3DCore::QNode *parent = nullptr) | |
| float | aspectRatio() const |
| float | bottom() const |
| float | exposure() const |
| float | farPlane() const |
| float | fieldOfView() const |
| float | left() const |
| Qt3DRender::QCameraLens * | lens() const |
| float | nearPlane() const |
| void | pan(float angle) |
| void | pan(float angle, const QVector3D &axis) |
| void | panAboutViewCenter(float angle) |
| void | panAboutViewCenter(float angle, const QVector3D &axis) |
| QQuaternion | panRotation(float angle) const |
| QVector3D | position() const |
| QMatrix4x4 | projectionMatrix() const |
| Qt3DRender::QCameraLens::ProjectionType | projectionType() const |
| float | right() const |
| void | roll(float angle) |
| void | rollAboutViewCenter(float angle) |
| QQuaternion | rollRotation(float angle) const |
| void | rotate(const QQuaternion &q) |
| void | rotateAboutViewCenter(const QQuaternion &q) |
| QQuaternion | rotation(float angle, const QVector3D &axis) const |
| void | tilt(float angle) |
| void | tiltAboutViewCenter(float angle) |
| QQuaternion | tiltRotation(float angle) const |
| float | top() const |
| Qt3DCore::QTransform * | transform() const |
| void | translate(const QVector3D &vLocal, Qt3DRender::QCamera::CameraTranslationOption option = TranslateViewCenter) |
| void | translateWorld(const QVector3D &vWorld, Qt3DRender::QCamera::CameraTranslationOption option = TranslateViewCenter) |
| QVector3D | upVector() const |
| QVector3D | viewCenter() const |
| QVector3D | viewVector() const |
公共槽位
| void | setAspectRatio(float aspectRatio) |
| void | setBottom(float bottom) |
| void | setExposure(float exposure) |
| void | setFarPlane(float farPlane) |
| void | setFieldOfView(float fieldOfView) |
| void | setLeft(float left) |
| void | setNearPlane(float nearPlane) |
| void | setPosition(const QVector3D &position) |
| void | setProjectionMatrix(const QMatrix4x4 &projectionMatrix) |
| void | setProjectionType(Qt3DRender::QCameraLens::ProjectionType type) |
| void | setRight(float right) |
| void | setTop(float top) |
| void | setUpVector(const QVector3D &upVector) |
| void | setViewCenter(const QVector3D &viewCenter) |
| void | viewAll() |
| void | viewEntity(Qt3DCore::QEntity *entity) |
| void | viewSphere(const QVector3D ¢er, float radius) |
信号
| void | aspectRatioChanged(float aspectRatio) |
| void | bottomChanged(float bottom) |
| void | exposureChanged(float exposure) |
| void | farPlaneChanged(float farPlane) |
| void | fieldOfViewChanged(float fieldOfView) |
| void | leftChanged(float left) |
| void | nearPlaneChanged(float nearPlane) |
| void | positionChanged(const QVector3D &position) |
| void | projectionMatrixChanged(const QMatrix4x4 &projectionMatrix) |
| void | projectionTypeChanged(Qt3DRender::QCameraLens::ProjectionType projectionType) |
| void | rightChanged(float right) |
| void | topChanged(float top) |
| void | upVectorChanged(const QVector3D &upVector) |
| void | viewCenterChanged(const QVector3D &viewCenter) |
| void | viewVectorChanged(const QVector3D &viewVector) |
成员类型文档
enum QCamera::CameraTranslationOption
此枚举指定了相机视图中心的平移方式
| 常量 | 值 | 描述 |
|---|---|---|
Qt3DRender::QCamera::TranslateViewCenter | 0 | 平移视图中心，同时保持视图方向不变 |
Qt3DRender::QCamera::DontTranslateViewCenter | 1 | 不平移视图中心，导致视图方向发生变化 |
属性文档
aspectRatio : float
保持当前的宽高比。
访问函数：
| float | aspectRatio() const |
| void | setAspectRatio(float aspectRatio) |
通知信号：
| void | aspectRatioChanged(float aspectRatio) |
bottom : float
保存摄像头的当前底部坐标。
此属性仅在projectionType 的值为QCameraLens::OrthographicProjection 时有效。
访问函数：
| float | bottom() const |
| void | setBottom(float bottom) |
通知信号：
| void | bottomChanged(float bottom) |
exposure : float
保存相机的当前曝光值。
默认值为 0.0。
Qt 3D 扩展包中的MetalRoughMaterial是目前唯一使用相机曝光的材质。负值会使材质变暗，正值会使材质变亮。
自定义材质可选择以不同的方式解释该值。
访问函数：
| float | exposure() const |
| void | setExposure(float exposure) |
通知信号：
| void | exposureChanged(float exposure) |
farPlane : float
存储当前摄像机的远平面。距离摄像机比 farPlane 更远的物体将不会被渲染。
访问函数：
| float | farPlane() const |
| void | setFarPlane(float farPlane) |
通知器信号：
| void | farPlaneChanged(float farPlane) |
fieldOfView : float
存储当前的垂直视场角（单位：度）。
该属性与aspectRatio 共同决定相机可见的场景范围。从这个角度来看，你可以将其类比为根据想要捕捉的场景范围，选择广角（水平视场角大）或长焦（水平视场角小）镜头。
fieldOfView 仅在projectionType 设置为QCameraLens::PerspectiveProjection 时才生效。
访问函数：
| float | fieldOfView() const |
| void | setFieldOfView(float fieldOfView) |
通知器信号：
| void | fieldOfViewChanged(float fieldOfView) |
left : float
存储摄像机当前的左坐标。
此属性仅在projectionType 的值为QCameraLens::OrthographicProjection 时有效。
访问函数：
| float | left() const |
| void | setLeft(float left) |
通知信号：
| void | leftChanged(float left) |
[read-only] lens : Qt3DRender::QCameraLens* const
保存相机的 Qt3DRender::QCameraLens 组件。
访问函数：
| Qt3DRender::QCameraLens * | lens() const |
nearPlane : float
用于指定当前摄像机的近平面。距离摄像机比 nearPlane 更近的物体将不会被渲染。
访问函数：
| float | nearPlane() const |
| void | setNearPlane(float nearPlane) |
通知器信号：
| void | nearPlaneChanged(float nearPlane) |
position : QVector3D
将摄像机的位置保持在相对于父实体的坐标系中。
访问函数：
| QVector3D | position() const |
| void | setPosition(const QVector3D &position) |
通知器信号：
| void | positionChanged(const QVector3D &position) |
projectionMatrix : QMatrix4x4
存储摄像机的当前投影矩阵。
访问函数：
| QMatrix4x4 | projectionMatrix() const |
| void | setProjectionMatrix(const QMatrix4x4 &projectionMatrix) |
通知信号：
| void | projectionMatrixChanged(const QMatrix4x4 &projectionMatrix) |
projectionType : Qt3DRender::QCameraLens::ProjectionType
存储相机投影的类型。默认值为QCameraLens::PerspectiveProjection 。
- QCameraLens::OrthographicProjection - 平行线看起来仍是平行的。物体无论距离远近，看起来大小都一样。
- QCameraLens::PerspectiveProjection - 平行线在远处看似相交。物体离相机越远，看起来就越小。
- QCameraLens::FrustumProjection
- QCameraLens::CustomProjection
访问函数：
| Qt3DRender::QCameraLens::ProjectionType | projectionType() const |
| void | setProjectionType(Qt3DRender::QCameraLens::ProjectionType type) |
通知器信号：
| void | projectionTypeChanged(Qt3DRender::QCameraLens::ProjectionType projectionType) |
另请参阅 Qt3DRender::QCameraLens::ProjectionType 。
right : float
保存相机的当前权限。
仅当projectionType 的值为QCameraLens::OrthographicProjection 时，此属性才起作用。
访问函数：
| float | right() const |
| void | setRight(float right) |
通知信号：
| void | rightChanged(float right) |
top : float
保存摄像机的当前顶点。
仅当projectionType 的值为QCameraLens::OrthographicProjection 时，此属性才有效。
访问函数：
| float | top() const |
| void | setTop(float top) |
通知信号：
| void | topChanged(float top) |
[read-only] transform : Qt3DCore::QTransform* const
保存相机的 Qt3DCore::QTransform 组件。
访问函数：
| Qt3DCore::QTransform * | transform() const |
upVector : QVector3D
存储相机“向上”向量，其坐标系相对于父实体。
“up”向量指示了摄像机顶部朝向的方向。不妨想象一下拍照的情景：在调整好位置并将摄像机对准目标后，你可以将摄像机向左或向右旋转，从而获得竖拍、横拍（或倾斜！）的画面。“upVector”允许你控制此类运动。
访问函数：
| QVector3D | upVector() const |
| void | setUpVector(const QVector3D &upVector) |
通知器信号：
| void | upVectorChanged(const QVector3D &upVector) |
viewCenter : QVector3D
将摄像机的视点中心保存在相对于父实体的坐标系中。
直观来说，viewCenter 就是摄像机所对准的位置。
访问函数：
| QVector3D | viewCenter() const |
| void | setViewCenter(const QVector3D &viewCenter) |
通知器信号：
| void | viewCenterChanged(const QVector3D &viewCenter) |
[read-only] viewVector : QVector3D
存储相机视向量，其坐标系相对于父实体。
该向量描述了从摄像机（position ）到其目标（viewCenter ）的位移。
访问函数：
| QVector3D | viewVector() const |
通知信号：
| void | viewVectorChanged(const QVector3D &viewVector) |
成员函数文档
[explicit] QCamera::QCamera(Qt3DCore::QNode *parent = nullptr)
使用指定的parent 创建一个新的QCamera实例。
Qt3DRender::QCameraLens *QCamera::lens() const
返回当前的镜头。
注意： 这是 lens 属性的获取器 函数。
[invokable] void QCamera::pan(float angle)
将摄像机的平移角度调整为angle （单位：度）。
注意：该 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] void QCamera::pan(float angle, const QVector3D &axis)
根据选定的axis ，将摄像机的平移角度调整为angle （单位为度）。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QCamera::panAboutViewCenter(float angle)
将摄像机的平移角度围绕视图中心调整angle 度。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QCamera::panAboutViewCenter(float angle, const QVector3D &axis)
以angle 为单位（单位为度），围绕视图中心调整摄像机的平移角度，该操作在axis 上进行。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QQuaternion QCamera::panRotation(float angle) const
返回相对于angle 计算出的平移旋转角度（以度为单位），用于调整摄像机的平移或Y轴上的左右旋转。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QCamera::roll(float angle)
将相机滚动角按angle 的值（单位：度）进行调整。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QCamera::rollAboutViewCenter(float angle)
将摄像机的滚动轴围绕视图中心按angle （单位：度）进行调整。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] QQuaternion QCamera::rollRotation(float angle) const
返回相对于angle 计算出的滚转角度（单位为度），该角度用于调整摄像机在Z轴上的滚转或左右倾斜。
注意： 可以通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] void QCamera::rotate(const QQuaternion &q)
使用q 中的四元数旋转摄像机。
注意：该 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] void QCamera::rotateAboutViewCenter(const QQuaternion &q)
利用q 中的四元数，围绕视图中心旋转摄像机。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] QQuaternion QCamera::rotation(float angle, const QVector3D &axis) const
返回相对于angle 的计算旋转角度（以度为单位），以及所选的axis 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[slot] void QCamera::setAspectRatio(float aspectRatio)
将摄像机的宽高比设置为aspectRatio 。
注意： 这是属性aspectRatio 的设置 函数。
另请参阅 aspectRatio()。
[slot] void QCamera::setBottom(float bottom)
将摄像机的底部设置为bottom 。
注意： 这是属性bottom 的设置 函数。
另请参阅 bottom()。
[slot] void QCamera::setExposure(float exposure)
将相机的曝光值设置为exposure 。
注意： 这是属性exposure 的设置 函数。
另请参阅 exposure()。
[slot] void QCamera::setFarPlane(float farPlane)
将摄像机的远平面设置为farPlane
注意： 这是属性farPlane 的设置 函数。
另请参阅 farPlane()。
[slot] void QCamera::setFieldOfView(float fieldOfView)
将摄像机的视场角设置为fieldOfView （单位：度）。
注意： 这是属性fieldOfView 的设置 函数。
另请参阅 fieldOfView()。
[slot] void QCamera::setLeft(float left)
将摄像机的左侧位置设置为left 。
注意： 这是属性left 的设置 函数。
另请参阅 left()。
[slot] void QCamera::setNearPlane(float nearPlane)
将摄像机的近平面设置为nearPlane 。
注意： 这是属性nearPlane 的设置 函数。
另请参阅 nearPlane()。
[slot] void QCamera::setPosition(const QVector3D &position)
将摄像机在三维空间中的位置设置为position 。
注意： 这是属性position 的设置 函数。
另请参阅 position()。
[slot] void QCamera::setProjectionMatrix(const QMatrix4x4 &projectionMatrix)
将摄像机的投影矩阵设置为projectionMatrix 。
注意： 这是属性projectionMatrix 的设置 函数。
另请参阅 projectionMatrix()。
[slot] void QCamera::setProjectionType(Qt3DRender::QCameraLens::ProjectionType type)
将摄像机的投影类型设置为type 。
注意： 这是属性projectionType 的设置 函数。
另请参阅 projectionType()。
[slot] void QCamera::setRight(float right)
将相机的右侧属性设置为right 。
注意： 这是属性right 的设置 函数。
另请参阅 right()。
[slot] void QCamera::setTop(float top)
将摄像机的顶部设置为top 。
注意： 这是属性top 的设置 函数。
另请参阅 top()。
[slot] void QCamera::setUpVector(const QVector3D &upVector)
将摄像机的向上向量设置为upVector 。
注意： 这是属性 `upVector`的设置 函数。
另请参阅 upVector()。
[slot] void QCamera::setViewCenter(const QVector3D &viewCenter)
将摄像机的视图中心设置为viewCenter 。
注意： 这是属性viewCenter 的设置 函数。
另请参阅 viewCenter()。
[invokable] void QCamera::tilt(float angle)
将摄像机的倾斜角度调整为angle 度。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
[invokable] void QCamera::tiltAboutViewCenter(float angle)
将摄像机相对于视图中心的俯仰角调整为angle 度。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QQuaternion QCamera::tiltRotation(float angle) const
返回相对于angle 的计算出的俯仰旋转角度（单位为度），该角度用于调整摄像机在X轴上的俯仰或上下旋转。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
Qt3DCore::QTransform *QCamera::transform() const
通过 transform 返回摄像机的位置。
注意： 这是属性 transform 的获取器 函数。
[invokable] void QCamera::translate(const QVector3D &vLocal, Qt3DRender::QCamera::CameraTranslationOption option = TranslateViewCenter)
将摄像机的位置及其视向量在本地坐标系中沿vLocal 方向平移。通过option 参数可以控制是否平移视图中心。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] void QCamera::translateWorld(const QVector3D &vWorld, Qt3DRender::QCamera::CameraTranslationOption option = TranslateViewCenter)
将摄像机的位置及其视向量在世界坐标系中沿vWorld 方向平移。option 参数用于控制是否平移视图中心。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[slot] void QCamera::viewAll()
旋转并移动摄像机，使其viewCenter 位于场景边界体积的中心，且整个场景都能容纳在视口内。
注意：仅 当镜头处于透视投影或正交投影模式时才有效。
另请参阅 Qt3D.Render::Camera::projectionType 。
[slot] void QCamera::viewEntity(Qt3DCore::QEntity *entity)
旋转并移动摄像机，使其viewCenter 位于entity 的包围体中心，且整个实体完全位于视口内。
注意：仅 当镜头处于透视投影或正交投影模式时才有效。
另请参阅 Camera.projectionType 。
[slot] void QCamera::viewSphere(const QVector3D ¢er, float radius)
旋转并移动摄像机，使其viewCenter 为center ，且一个radius 的球体刚好能容纳在视口内。
注意：仅 在镜头处于透视投影或正交投影模式时有效。
© 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.
