【OSG学习笔记】Day 46: CameraManipulator（相机操控器）

CameraManipulator 相机操控器

在 OpenSceneGraph（OSG）三维开发中，** 相机操控器（Camera Manipulator）** 是连接用户交互与三维视角变换的核心桥梁，它决定了用户如何通过鼠标、键盘控制虚拟相机在场景中移动、旋转与观察。

本文结合 TravelManipulator 代码，详解 CameraManipulator 的继承体系、核心接口，以及从 MatrixManipulator 升级的底层原因与实践要点。

---

什么是 osgGA::CameraManipulator

osgGA::CameraManipulator 是 OpenSceneGraph 3.x 及以上版本中，所有相机交互控制器的顶级基类 。

它的作用：

1. 接收鼠标、键盘事件
2. 计算相机的位置、姿态
3. 输出相机视图矩阵给渲染管线
4. 是自定义漫游、飞行、轨迹球、驾驶等相机模式的唯一标准入口

---

完整继承关系（非常重要）

osgGA::CameraManipulator 是 OSG 中所有相机操控器的抽象基类 ，归属 osgGA（OSG GUI 事件与交互）模块，核心职责是定义相机控制的标准接口、处理 GUI 输入事件（鼠标/键盘/触摸），并输出相机的视图矩阵，最终驱动场景渲染视角的更新。

它本质是一个事件处理器 + 矩阵计算器，既继承了 OSG 的基础对象体系，也具备 GUI 事件响应能力，是自定义相机操控的唯一标准入口。

1. 完整继承关系

CameraManipulator 的继承体系清晰分层，体现了 OSG "模块化、可复用"的设计思想，层级如下：

osg::Referenced（智能指针引用基类，实现自动内存管理）
    ↓
osg::Object（OSG 所有对象基类，提供名称、克隆、类型判断等基础能力）
    ↓
osgGA::GUIEventHandler（GUI 事件处理器基类，定义事件处理入口 handle()）
    ↓
osgGA::CameraManipulator（抽象相机操控器，核心接口与相机逻辑）
    ↓
osgGA::StandardManipulator（标准操控器基类，封装平移、旋转、缩放通用逻辑）
    ↓
osgGA::TrackballManipulator / DriveManipulator / FlightManipulator（内置操控器）
    ↓
自定义操控器（如本文的 TravelManipulator）

2. 核心纯虚接口（必须实现）

作为抽象类，CameraManipulator 定义了 4 个核心纯虚函数，自定义操控器必须全部重写 ，这也是 TravelManipulator 代码中关键实现部分：

// 1. 通过矩阵直接设置操控器位置（视图矩阵）
virtual void setByMatrix(const osg::Matrixd& matrix) = 0;
// 2. 通过逆矩阵设置操控器位置（常用作相机视图矩阵的逆）
virtual void setByInverseMatrix(const osg::Matrixd& matrix) = 0;
// 3. 获取当前操控器的视图矩阵（相机位置+姿态最终输出矩阵）
virtual osg::Matrixd getMatrix() const = 0;
// 4. 获取当前操控器视图矩阵的逆矩阵（渲染管线核心参数）
virtual osg::Matrixd getInverseMatrix() const = 0;

结合 TravelManipulator 代码解析：

• setByMatrix/setByInverseMatrix：代码中为空实现，因自定义漫游操控器无需外部矩阵主动设置，仅通过事件自主更新位置与姿态，属于合理简化；
• getMatrix ：核心实现！通过 m_vRotation（姿态）和 m_vPosition（位置）计算旋转矩阵，再与平移矩阵组合，输出最终相机视图矩阵，决定场景的观察视角；
• getInverseMatrix ：直接返回 getMatrix() 的逆矩阵，OSG 渲染时会将其传入相机，用于顶点坐标的视图变换，是每一帧渲染都会调用的关键接口。

3. 事件处理核心：handle() 函数

CameraManipulator 继承自 GUIEventHandler，因此必须实现 handle() 虚函数，所有鼠标、键盘交互逻辑均在此处理 。TravelManipulator 的 handle() 函数是整个操控器的"交互中枢"：

• 监听 KEYDOWN 事件：处理 W/S/A/D 移动、方向键旋转、+/- 调速等键盘操作；
• 监听 PUSH/DRAG/RELEASE 事件：处理鼠标左键拖拽旋转视角逻辑；
• 事件处理完成后返回 true（事件已消费）或 false（事件未处理），确保交互响应流畅。

从 MatrixManipulator 到 CameraManipulator

早期 OSG 2.x 版本中，相机操控器的基类是 osgGA::MatrixManipulator，但从 OSG 3.0 版本开始 ，MatrixManipulator 被正式弃用（Deprecated） ，并更名为 CameraManipulator，头文件也从 <osgGA/MatrixManipulator> 改为 <osgGA/CameraManipulator>。

这一更名并非简单重命名，而是 OSG 架构优化、语义统一、功能扩展的必然结果，核心原因如下：

1. 语义更精准：回归"相机控制"本质

• MatrixManipulator：名称聚焦"矩阵操作"，仅强调其"计算变换矩阵"的技术属性，忽略了"控制相机"的核心功能，易让开发者误解为"通用矩阵工具"；
• CameraManipulator ：名称直接体现"相机操控器"的定位，明确其职责是专门控制 OSG Camera 对象，语义清晰、职责单一，符合面向对象"见名知意"的设计原则。

2. 架构更统一：整合事件与相机逻辑

MatrixManipulator 时期，事件处理与相机控制逻辑相对割裂，而 CameraManipulator 直接继承 osgGA::GUIEventHandler，将"事件响应"与"相机矩阵计算"深度整合：

• 无需额外绑定事件处理器，操控器自身就是事件处理器，通过 viewer->setCameraManipulator() 即可完成"相机绑定 + 事件注册"，简化代码流程；
• 优化了事件传递机制，确保鼠标/键盘输入能实时、高效地转化为相机姿态更新，提升交互流畅度。

3. 功能更强大：扩展相机专属能力

CameraManipulator 在 MatrixManipulator 基础上，新增了多个相机专属接口，适配现代三维交互需求：

• 新增 setCoordinateFrameCallback()：支持自定义坐标系（如设置 UP 轴为 Y 轴或 Z 轴），适配不同场景（地理信息、工业建模）的坐标系规范；
• 优化相机状态管理：新增相机 home 位置、自动适配场景包围球、多相机切换等辅助接口，内置操控器（如轨迹球、飞行操控器）功能更完善；
• 兼容多线程渲染：接口设计适配 OSG 多线程渲染架构，避免矩阵计算与渲染线程的冲突，提升高并发场景稳定性。

4. 兼容性与维护：旧类彻底移除，新类标准化

• OSG 3.x 之后的版本（如 3.4、3.6、3.7）彻底移除了 MatrixManipulator 头文件与类定义 ，直接导致 #include <osgGA/MatrixManipulator> 报错"没有那个文件或目录"；
• OSG 官方后续所有更新、文档、示例均基于 CameraManipulator，MatrixManipulator 无任何维护支持，使用旧类会导致代码无法跨版本兼容、问题难以排查。

完整可运行工程代码（复制即用）

📄 1. ManipulatorTravel.h

#pragma once

#include <osgViewer/Viewer>
#include <osg/LineSegment>
#include <osg/Geometry>
#include <osg/Node>
#include <osgGA/CameraManipulator>
#include <osgUtil/IntersectVisitor>

class TravelManipulator : public osgGA::CameraManipulator
{
public:
    TravelManipulator();
    ~TravelManipulator();

    static TravelManipulator* TravelToScene(osg::ref_ptr<osgViewer::Viewer> viewer);

private:
    osg::ref_ptr<osgViewer::Viewer> m_pHostViewer;
    float m_fMoveSpeed;
    osg::Vec3 m_vPosition;
    osg::Vec3 m_vRotation;

public:
    bool m_bLeftButtonDown;
    float m_fpushY;
    float m_fpushX;

    virtual void setByMatrix(const osg::Matrixd& matrix) override;
    virtual void setByInverseMatrix(const osg::Matrixd& matrix) override;
    virtual osg::Matrixd getMatrix(void) const override;
    virtual osg::Matrixd getInverseMatrix(void) const override;

    virtual bool handle(const osgGA::GUIEventAdapter& ea, osgGA::GUIActionAdapter& us) override;

    float m_fAngle;
    void ChangePosition(const osg::Vec3& delta);

    bool m_bPeng;

    float getSpeed();
    void setSpeed(float &sp);

    void SetPosition(osg::Vec3 &position);
    osg::Vec3 GetPosition();
};

---

📄 2. ManipulatorTravel.cpp

#include "ManipulatorTravel.h"

TravelManipulator::TravelManipulator() :
    m_fMoveSpeed(5.0f),
    m_bLeftButtonDown(false),
    m_fpushX(0),
    m_fAngle(3.0f),
    m_bPeng(false),
    m_fpushY(0)
{
    m_vPosition = osg::Vec3(0, -100, 10);
    m_vRotation = osg::Vec3(osg::DegreesToRadians(89.0), 0.0, 0.0);
}

TravelManipulator::~TravelManipulator()
{
}

TravelManipulator* TravelManipulator::TravelToScene(osg::ref_ptr<osgViewer::Viewer> viewer)
{
    TravelManipulator* camera = new TravelManipulator;
    viewer->setCameraManipulator(camera);
    camera->m_pHostViewer = viewer;
    return camera;
}

void TravelManipulator::setByMatrix(const osg::Matrixd& matrix)
{
}

void TravelManipulator::setByInverseMatrix(const osg::Matrixd& matrix)
{
}

osg::Matrixd TravelManipulator::getMatrix(void) const
{
    osg::Matrixd mat;
    mat.makeRotate(
        m_vRotation.x(), osg::Vec3(1,0,0),
        m_vRotation.y(), osg::Vec3(0,1,0),
        m_vRotation.z(), osg::Vec3(0,0,1)
    );
    return mat * osg::Matrixd::translate(m_vPosition);
}

osg::Matrixd TravelManipulator::getInverseMatrix(void) const
{
    return osg::Matrixd::inverse(getMatrix());
}

bool TravelManipulator::handle(const osgGA::GUIEventAdapter& ea, osgGA::GUIActionAdapter& us)
{
    float mouseX = ea.getX();
    float mouseY = ea.getY();

    switch (ea.getEventType())
    {
        case osgGA::GUIEventAdapter::KEYDOWN:
        {
            if (ea.getKey() == 0x20) {
                us.requestRedraw();
                us.requestContinuousUpdate(false);
                return true;
            }
            if (ea.getKey() == 0xFF50) {
                ChangePosition(osg::Vec3(0, 0, m_fMoveSpeed));
                return true;
            }
            if (ea.getKey() == 0xFF57) {
                ChangePosition(osg::Vec3(0, 0, -m_fMoveSpeed));
                return true;
            }
            if (ea.getKey() == '+') {
                m_fMoveSpeed += 1;
                return true;
            }
            if (ea.getKey() == '-') {
                m_fMoveSpeed -= 1;
                if (m_fMoveSpeed < 1) m_fMoveSpeed = 1;
                return true;
            }
            if (ea.getKey() == 'W' || ea.getKey() == 'w' || ea.getKey() == 0xFF52) {
                ChangePosition(osg::Vec3(
                    m_fMoveSpeed * cosf(osg::PI_2 + m_vRotation.z()),
                    m_fMoveSpeed * sinf(osg::PI_2 + m_vRotation.z()),
                    0
                ));
                return true;
            }
            if (ea.getKey() == 'S' || ea.getKey() == 's' || ea.getKey() == 0xFF54) {
                ChangePosition(osg::Vec3(
                    -m_fMoveSpeed * cosf(osg::PI_2 + m_vRotation.z()),
                    -m_fMoveSpeed * sinf(osg::PI_2 + m_vRotation.z()),
                    0
                ));
                return true;
            }
            if (ea.getKey() == 'A' || ea.getKey() == 'a') {
                ChangePosition(osg::Vec3(
                    -m_fMoveSpeed * sinf(osg::PI_2 + m_vRotation.z()),
                    m_fMoveSpeed * cosf(osg::PI_2 + m_vRotation.z()),
                    0
                ));
                return true;
            }
            if (ea.getKey() == 'D' || ea.getKey() == 'd') {
                ChangePosition(osg::Vec3(
                    m_fMoveSpeed * sinf(osg::PI_2 + m_vRotation.z()),
                    -m_fMoveSpeed * cosf(osg::PI_2 + m_vRotation.z()),
                    0
                ));
                return true;
            }
            if (ea.getKey() == 0xFF53) {
                m_vRotation.z() -= osg::DegreesToRadians(m_fAngle);
                return true;
            }
            if (ea.getKey() == 0xFF51) {
                m_vRotation.z() += osg::DegreesToRadians(m_fAngle);
                return true;
            }
            if (ea.getKey() == 'F' || ea.getKey() == 'f') {
                m_fAngle -= 0.2f;
                return true;
            }
            if (ea.getKey() == 'G' || ea.getKey() == 'g') {
                m_fAngle += 0.2f;
                return true;
            }
            break;
        }
        case osgGA::GUIEventAdapter::PUSH:
        {
            if (ea.getButton() == 1) {
                m_fpushX = mouseX;
                m_fpushY = mouseY;
                m_bLeftButtonDown = true;
            }
            break;
        }
        case osgGA::GUIEventAdapter::DRAG:
        {
            if (m_bLeftButtonDown) {
                m_vRotation.z() -= osg::DegreesToRadians(m_fAngle * (mouseX - m_fpushX));
                m_vRotation.x() += osg::DegreesToRadians(1.1f * (mouseY - m_fpushY));

                if (m_vRotation.x() >= osg::PI / 2)
                    m_vRotation.x() = osg::PI / 2;
                if (m_vRotation.x() <= 0)
                    m_vRotation.x() = 0;
            }
            break;
        }
        case osgGA::GUIEventAdapter::RELEASE:
        {
            if (ea.getButton() == 1)
                m_bLeftButtonDown = false;
            break;
        }
        default:
            break;
    }
    return false;
}

void TravelManipulator::ChangePosition(const osg::Vec3& delta)
{
    m_vPosition += delta;
}

void TravelManipulator::setSpeed(float &sp)
{
    m_fMoveSpeed = sp;
}

float TravelManipulator::getSpeed()
{
    return m_fMoveSpeed;
}

void TravelManipulator::SetPosition(osg::Vec3 &position)
{
    m_vPosition = position;
}

osg::Vec3 TravelManipulator::GetPosition()
{
    return m_vPosition;
}

---

📄 3. main.cpp

#include <osgViewer/Viewer>
#include <osgDB/ReadFile>
#include <osgUtil/Optimizer>
#include <iostream>
#include "ManipulatorTravel.h"

int main()
{
    osg::ref_ptr<osgViewer::Viewer> viewer = new osgViewer::Viewer;
    TravelManipulator::TravelToScene(viewer);

    osg::ref_ptr<osg::Group> root = new osg::Group;
    osg::ref_ptr<osg::Node> node = osgDB::readNodeFile("cow.osg");

    if (!node) {
        std::cerr << "模型加载失败！请把 cow.osg 放在程序同目录" << std::endl;
        return -1;
    }

    root->addChild(node);
    viewer->setSceneData(root);
    viewer->realize();
    return viewer->run();
}

---

总结

CameraManipulator 是 OSG 三维交互的基石，它替代 MatrixManipulator 是语义优化、架构升级、功能扩展的必然结果，不仅解决了旧类的命名模糊、架构割裂问题，更提供了标准化、高效、易扩展的相机控制接口。

我们的 TravelManipulator 正是基于这一新一代基类，通过规范继承、核心接口实现、交互逻辑封装，实现了稳定流畅的第一人称漫游功能。