Back to Qt.io
Contact Us Blog Download Qt

Qt3DRender::QCamera Class

class Qt3DRender::QCamera

QCamera 类定义了一个视点，通过它可以渲染场景。更多

头文件： #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 &center, 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::TranslateViewCenter0平移视图中心，使视图方向保持不变
Qt3DRender::QCamera::DontTranslateViewCenter1不平移视图中心，导致视图方向改变

属性文档

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 Extras 中的MetalRoughMaterial 是目前唯一使用摄像机曝光的素材。负值会使材质变暗，正值会使材质变亮。

自定义材质可以选择不同的值。

访问功能：

float exposure() const
void setExposure(float exposure)

通知信号：

void exposureChanged(float exposure)

farPlane : float

保存当前的摄像机远平面。距离摄像机比远平面更远的物体将不会被渲染。

访问功能：

float farPlane() const
void setFarPlane(float farPlane)

通知信号：

void farPlaneChanged(float farPlane)

fieldOfView : float

当前垂直视场的度数。

与aspectRatio 一样，该属性决定了摄像机能看到多少场景。在这方面，您可以认为它类似于选择广角镜头（水平视野宽）或长焦镜头（水平视野窄），这取决于您想拍摄多少场景。

只有当projectionType 是QCameraLens::PerspectiveProjection 时，fieldOfView 才有意义。

访问功能：

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

保存当前摄像机的近平面。距离摄像机比近平面更近的物体将不会被渲染。

访问功能：

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 。

访问功能：

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

保存摄像机相对于父实体的向上矢量坐标。

向上矢量表示相机顶部朝向的方向。想象一下拍照：在定位并将相机对准目标后，您可能会左右旋转相机，从而获得纵向或横向（或倾斜！）的照片。

访问功能

QVector3D upVector() const
void setUpVector(const QVector3D &upVector)

通知信号

void upVectorChanged(const QVector3D &upVector)

viewCenter : QVector3D

以相对于父实体的坐标表示摄像机的视图中心。

直观地说，视图中心就是摄像机指向的位置。

访问功能：

QVector3D viewCenter() const
void setViewCenter(const QVector3D &viewCenter)

通知信号

void viewCenterChanged(const QVector3D &viewCenter)

[read-only] viewVector : const QVector3D

保存摄像机相对于父实体的坐标视图向量。

该向量描述了从摄像机 (position) 到目标 (viewCenter) 的位移。

访问功能：

QVector3D viewVector() const

Notifier 信号：

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)

将摄像机在 3D 空间中的位置设置为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 的获取函数。

[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 &center, float radius)

旋转并移动摄像机，使其viewCenter 是center ，并使radius 的球体与视口相吻合。

注： 只有当镜头处于透视或正投影模式时才有效。

另请参阅 Qt3D.Render::Camera::projectionType 。

© 2025 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.