【OSG学习笔记】Day 52: FadeText

osgText::FadeText 用法详解与实战

在 OpenSceneGraph（OSG）的文字渲染模块中，osgText::FadeText 是基于距离实现自动淡入淡出的核心类，它解决了普通文字无论远近都保持固定显示的问题，能根据相机与文字的距离自动调整透明度，让三维场景中的文字渲染更自然、更轻量化。

本文将全面解析 FadeText 的特性、继承关系、核心用法，并提供可直接编译运行的完整实战代码。

osgText::FadeText 核心特性

osgText::FadeText 是 OSG 专为距离关联的透明渐变文字设计的绘制类，核心特性如下：

1. 自动淡入淡出：无需手动编写动画逻辑，根据相机与文字的距离，自动实现「远处透明、近处清晰」的效果；
2. 继承普通文字能力：完全保留文字设置、字体、颜色、大小、朝向等基础功能；
3. 场景优化友好：远距离文字自动透明/隐藏，减少渲染压力，提升场景性能；
4. 兼容三维场景：支持广告牌效果（始终面向相机），适配各类三维模型、地形场景。

关键区别：osgText::Text 是静态文字（永远不透明），osgText::FadeText 是动态渐变文字，是 OSG 文字渲染的进阶方案。

类继承关系

osgText::FadeText 并非独立类，而是基于 OSG 底层绘制与文字基类的派生类，完整继承关系：

osg::Object → osg::Drawable → osgText::TextBase → osgText::Text → osgText::FadeText

1. osg::Drawable：OSG 所有可绘制对象的基类，赋予渲染能力；
2. osgText::TextBase：文字渲染抽象基类，定义文字通用接口；
3. osgText::Text：普通文字实现类，基础文字渲染核心；
4. osgText::FadeText ：最终派生类，新增淡入淡出逻辑，扩展了距离透明功能。

这意味着：所有 Text 支持的用法，FadeText 都可以直接使用，同时额外拥有渐变特性。

核心 API 与使用要点

基于实战代码，我们梳理 FadeText 必用的关键方法：

1. 对象创建 ：osgText::FadeText* text = new osgText::FadeText();
2. 文字内容 ：text->setText(内容)，支持字符串、数字转换；
3. 字体设置 ：text->setFont(字体路径)，支持系统字体、自定义字体；
4. 空间位置 ：text->setPosition(osg::Vec3(x,y,z))，设置三维坐标；
5. 文字大小 ：text->setCharacterSize(大小) + 大小模式，适配屏幕/三维坐标；
6. 文字颜色 ：text->setColor(osg::Vec4(r,g,b,a))，RGBA 格式（0~1）；
7. 面向屏幕 ：text->setAutoRotateToScreen(true)，广告牌效果，文字始终正对相机；
8. 渐变触发 ：配合 osg::ClusterCullingCallback 实现距离渐变（全版本通用）。

完整实战代码

#include <osgViewer/Viewer>
#include <osg/Geode>
#include <osg/Group>
#include <osg/StateSet>
#include <osg/ClusterCullingCallback>
#include <osgText/FadeText>

// 使用OSG命名空间，简化代码书写
using namespace osg;
using namespace osgText;

/// 创建一排带淡入淡出效果的FadeText文字
ref_ptr<Node> createFadeTextDemo()
{
    // 根节点：管理所有文字对象
    ref_ptr<Group> rootNode = new Group;
    ref_ptr<Geode> drawableNode = new Geode;
    rootNode->addChild(drawableNode);

    // 渲染状态设置：关闭深度测试+关闭光照，保证文字100%可见
    ref_ptr<StateSet> stateSet = rootNode->getOrCreateStateSet();
    stateSet->setMode(GL_DEPTH_TEST, StateAttribute::OFF);    // 关闭深度遮挡
    stateSet->setMode(GL_LIGHTING, StateAttribute::OFF);       // 关闭光照，文字不受光影影响

    // 循环创建20个文字，排成一排
    for (int i = 0; i < 20; ++i)
    {
        // 1. 创建FadeText对象
        FadeText* text = new FadeText;

        // 2. 设置文字内容
        text->setText("Hello");

        // 3. 设置字体路径（相对路径，可根据项目修改）
        text->setFont("../../fonts/arial.ttf");

        // 4. 设置文字三维位置：水平排成一排
        text->setPosition(Vec3(-50 + i * 5, -50 + i * 5, 0));

        // 5. 设置文字大小与渲染模式
        text->setCharacterSize(30.0f);                          // 文字大小
        text->setCharacterSizeMode(Text::SCREEN_COORDS);        // 屏幕坐标模式，大小固定

        // 6. 设置文字颜色：纯白色（RGBA：1,1,1,1）
        text->setColor(Vec4(1.0f, 1.0f, 1.0f, 1.0f));

        // 7. 关键：文字始终面向屏幕（广告牌效果）
        text->setAutoRotateToScreen(true);

        // 8. FadeText核心：设置距离渐变回调（全OSG版本通用）
        osg::Vec3 textPos = text->getPosition();
        osg::Vec3 normal(0.0f, 0.0f, 1.0f);
        float fadeDistance = 200.0f; // 渐变触发距离
        text->setCullCallback(new osg::ClusterCullingCallback(textPos, normal, fadeDistance));

        // 将文字添加到可绘制节点
        drawableNode->addDrawable(text);
    }

    return rootNode;
}

/// 主函数：OSG窗口渲染
int main()
{
    // 创建OSG查看器
    osgViewer::Viewer viewer;

    // 设置渲染场景：淡入淡出文字
    viewer.setSceneData(createFadeTextDemo());

    // 设置窗口背景色：灰色，突出白色文字
    viewer.getCamera()->setClearColor(Vec4(0.2f, 0.2f, 0.2f, 1.0f));

    // 启动渲染循环
    return viewer.run();
}

使用场景

适用场景

1. 三维场景中的距离提示文字（如地标、标注）；
2. 需要优化渲染性能的大量文字场景；
3. 仿真、可视化项目中的动态文字效果；
4. 替代普通文字，提升场景真实感与流畅度。

总结

1. osgText::FadeText 是 osgText::Text 的派生类，兼容所有普通文字用法；
2. 核心能力是根据相机距离自动淡入淡出，无需手动编写动画；
3. 配合 ClusterCullingCallback 可实现全版本兼容的渐变效果；
4. 关闭光照、深度测试后，文字渲染更稳定，无隐藏、黑屏问题。

---