【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命名空间，简化代码书写usingnamespaceosg;usingnamespaceosgText;/// 创建一排带淡入淡出效果的FadeText文字ref_ptr<Node>createFadeTextDemo(){// 根节点：管理所有文字对象ref_ptr<Group>rootNode=newGroup;ref_ptr<Geode>drawableNode=newGeode;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(inti=0;i<20;++i){// 1. 创建FadeText对象FadeText*text=newFadeText;// 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::Vec3normal(0.0f,0.0f,1.0f);floatfadeDistance=200.0f;// 渐变触发距离text->setCullCallback(newosg::ClusterCullingCallback(textPos,normal,fadeDistance));// 将文字添加到可绘制节点drawableNode->addDrawable(text);}returnrootNode;}/// 主函数：OSG窗口渲染intmain(){// 创建OSG查看器osgViewer::Viewer viewer;// 设置渲染场景：淡入淡出文字viewer.setSceneData(createFadeTextDemo());// 设置窗口背景色：灰色，突出白色文字viewer.getCamera()->setClearColor(Vec4(0.2f,0.2f,0.2f,1.0f));// 启动渲染循环returnviewer.run();}

使用场景

适用场景

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

总结

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