【OSG学习笔记】Day 53: Text3D（ 三维文字）

三维文字渲染：osgText::Text3D

在 OpenSceneGraph（OSG）开发中，文字渲染是场景标注、信息展示的核心功能。

除了之前介绍的平面淡入淡出文字 FadeText ，OSG 还提供了真正的三维立体文字 ------osgText::Text3D，它能生成具有厚度、立体感、可旋转、可缩放的3D文字模型，广泛应用于三维仿真、数字孪生、场景标识、广告展示等领域。

本文将从继承关系、核心特性、API详解、完整代码、使用场景 全方位讲解Text3D，带你彻底掌握OSG三维文字开发。

---

核心特性

osgText::Text3D 是OSG专门为三维空间立体文字设计的绘制类，核心优势：

1. 真正的3D模型：文字拥有厚度，不是平面贴片，可360°查看；
2. 独立渲染属性：支持自定义文字厚度、渲染模式、对齐方式、包围盒显示；
3. 兼容材质/光照：可设置颜色、反光、透明度，和三维模型渲染逻辑完全一致；
4. 灵活布局：支持指定三维坐标、对齐平面，适配任意三维场景；
5. 可组合使用：能和模型、地形、粒子特效等场景元素无缝融合。

✅ 关键对比

• osgText::Text：二维平面文字，始终面向相机，无厚度；
• osgText::FadeText：带距离渐变的二维文字，无厚度；
• osgText::Text3D：三维立体模型文字，有长宽高，可旋转观察。

---

类继承关系

Text3D 拥有标准的OSG继承链，和普通文字同源，扩展性极强：

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

1. osg::Object：OSG所有对象的基类，提供引用计数；
2. osg::Drawable：可绘制对象基类，具备渲染能力；
3. osgText::TextBase：文字抽象基类，定义文字通用接口；
4. osgText::Text：二维文字基类，实现基础文字渲染；
5. osgText::Text3D ：三维文字最终类，扩展立体、厚度、模型化功能。

这意味着：所有 Text 支持的功能，Text3D 都可以直接使用，并额外拥有3D专属属性。

---

核心API方法详解

结合实战代码，Text3D 最常用的关键API如下：

API 方法	功能说明
setText(字符串)	设置文字内容，支持中文/英文/数字
setFont(路径)	设置字体文件（ttf/otf）
setPosition(Vec3)	设置文字三维空间坐标
setCharacterSize(大小)	设置文字尺寸
setCharacterDepth(厚度)	3D专属：设置文字立体厚度
setRenderMode(模式)	设置文字渲染模式
setDrawMode(模式)	设置绘制方式（文字/包围盒）
setAxisAlignment(模式)	设置文字对齐平面（XY/XZ/YZ）

---

完整可运行代码

#include <osgViewer/Viewer>
#include <osgDB/ReadFile>
#include <osgDB/WriteFile>
#include <osgText/Text3D>
#include <osgText/Font3D>
#include <osgText/Text>
#include <osgUtil/Optimizer>
#include <osg/Geode>
#include <osg/Group>
#include <osg/Material>
#include <osg/StateSet>
#include <iostream>

// 创建三维立体文字
osg::ref_ptr<osg::Geode> create3DText()
{
    osg::ref_ptr<osg::Geode> geode = new osg::Geode();

    // 创建 3D 文字对象
    osg::ref_ptr<osgText::Text3D> text3D = new osgText::Text3D();

    // ========== 1. 基础文字设置 ==========
    // 文字内容（支持中文，需配套中文字体）
    text3D->setText(L"http://www.OsgChina.org --- OpenSceneGraph 三维文字");
    // 字体路径（必须使用支持中文的字体）
    text3D->setFont("../../fonts/simhei.ttf");
    // 文字大小
    text3D->setCharacterSize(60.0f);
    // 文字三维位置
    text3D->setPosition(osg::Vec3(0.0f, 0.0f, 0.0f));

    // ========== 2. 3D文字专属设置 ==========
    // 渲染模式：按字形独立渲染
    text3D->setRenderMode(osgText::Text3D::PER_GLYPH);
    // 文字厚度（核心3D属性）
    text3D->setCharacterDepth(10.0f);
    // 绘制模式：显示文字 + 包围盒
    text3D->setDrawMode(osgText::Text3D::TEXT | osgText::Text3D::BOUNDINGBOX);
    // 对齐平面：XZ平面（地面水平显示）
    text3D->setAxisAlignment(osgText::Text3D::XZ_PLANE);

    // ========== 3. 材质与光照 ==========
    osg::ref_ptr<osg::Material> material = new osg::Material();
    // 环境光 + 漫反射 = 白色立体文字
    material->setAmbient(osg::Material::FRONT_AND_BACK, osg::Vec4(1.0f, 1.0f, 1.0f, 1.0f));
    material->setDiffuse(osg::Material::FRONT_AND_BACK, osg::Vec4(1.0f, 1.0f, 1.0f, 1.0f));
    material->setAlpha(osg::Material::FRONT_AND_BACK, 1.0f);

    // 将材质应用到节点
    geode->getOrCreateStateSet()->setAttribute(material.get());
    geode->addDrawable(text3D.get());

    return geode;
}

// 主函数
int main()
{
    // 创建OSG窗口
    osg::ref_ptr<osgViewer::Viewer> viewer = new osgViewer::Viewer();
    osg::ref_ptr<osg::Group> root = new osg::Group();

    // 添加3D文字
    root->addChild(create3DText());

    // 优化场景
    osgUtil::Optimizer optimizer;
    optimizer.optimize(root.get());

    // 启动渲染
    viewer->setSceneData(root.get());
    viewer->realize();
    viewer->run();

    return 0;
}

---

使用场景

osgText::Text3D 适用于以下专业场景：

1. 三维场景标识：建筑名称、道路指示牌、设备标注
2. 数字孪生系统：车间、场馆、城市三维看板文字
3. 仿真训练系统：三维环境中的操作提示
4. 展览展示项目：立体广告、标题、logo
5. 游戏与可视化：3D空间内的文字特效

---

总结

1. osgText::Text3D 是三维立体文字模型，拥有厚度与真实3D结构；
2. 继承自Text，兼容二维文字所有功能，并扩展3D属性；
3. 核心API：setCharacterDepth（厚度）、setAxisAlignment（对齐）、setRenderMode（渲染）；
4. 必须搭配材质+字体才能正常显示；
5. 是OSG开发中三维信息展示的标准方案。

---