SpeedTree Cross-Platform Foliage SDK
A pure C++20, graphics-API-agnostic implementation of SpeedTree foliage rendering and wind dynamics for cross-platform game engines.
🌟 核心特性与渲染真实度突破(Realism & Shading)
为了达到与商业版 SpeedTree 同样真实、飘逸自然的渲染质感,本 SDK 实现了以下四大核心技术管线:
1. 三级分层风场动力学 (3-Tier Hierarchical Wind Dynamics)
- Level 1 树干弯曲 (Trunk Bending): 基于树高的二次曲线响应,具备长度保持(Length-Preserving)算法,模拟主干在阵风下的柔韧弯曲。
- Level 2 树枝摇曳 (Branch Sway): 引入大分支相对主干的摆动阻尼与相位差(Phase Offset),营造起伏有致的林间韵律。
- Level 3 叶片自转翻滚与颤动 (Leaf Flutter & Tumble): 这是“飘逸感”的最关键核心。每个树叶卡片顶点都绑定了叶片局部中心锚点(
leaf_pivot_offset)。在微风与阵风下,叶片围绕自身锚点高频翻滚微颤,光影鳞鳞闪烁,彻底消除僵硬片状感。 - 空间阵风波 (Spatial Gust Waves): 风场跨越坐标系传递低频起伏波,使森林呈现一波波风浪拂过的生动波纹。
2. 树冠球形法线混合 (Canopy Spherical Normal Blending)
- 传统 Billboard/插片树叶最大的痛点是“纸片感”与法线杂乱破碎。
- 本 SDK 在几何生成和 Shader 中自动计算以树冠重心为起点的虚拟球形法线(Spherical Normal),并与叶片原始朝向做柔和加权混合。即使是由十字交叉面片组成的树冠,在阳光下也能呈现出浑厚、饱满的体积感。
3. 次表面透射与半兰伯特环绕光 (Subsurface Scattering & Wrap Lighting)
- 背光透射 (Subsurface Transmission): 逆光观察树木时,阳光穿透薄叶片,Shader 自动产生透光的翠绿光晕(
viewThrough = pow(dot(-L, V), 3.5))。 - 半兰伯特环绕光 (Wrap Lighting): 漫反射平滑过渡,背光区域不会死黑。
- 树冠内部自遮挡 (Canopy Interior AO): 依据叶片距树冠中心的距离衰减环境光,外层明亮透光、内部深邃幽暗。
4. 跨平台双管线支持 (Modern GPU Shader + CPU Fallback)
- 现代 GPU 管线: 提供标准的
foliage_shaders.h(GLSL 450 / Vulkan SPIR-V / Metal / D3D11-12 兼容),顶点着色器硬件级高帧率解算风力与球形法线。 - CPU Fallback 管线: 提供
EvaluateCpuTransformedVertices(),在老旧驱动或无自定义 Shader 环境下依然能实时计算风力变形。
📁 模块架构
sdk/speedtree/
├── include/speedtree/
│ ├── speedtree.h # 核心模型、顶点布局、SPT 信息、森林实例管理
│ └── foliage_shaders.h # 现代 GPU 植被顶点/片元着色器源码(含 3 级风力与次表面透光)
├── src/
│ ├── spt_parser.cpp # 官方 .spt 二进制解析(Token 2000/2001/10000/10002/12000 等)
│ ├── tree_generator.cpp # 树木骨架圆柱网格、树冠卡片、风力权重生成与 CPU 变形求值
│ └── forest.cpp # 森林多实例生命周期、视锥剔除基础、风向风力统一控制
└── tests/
└── speedtree_test.cpp # 单元测试(生成、Token 嗅探、风力位移)
🚀 集成与使用示例
#include <speedtree/speedtree.h>
// 1. 创建树木模板(可从 .spt 文件或通过参数化生成)
auto model = speedtree::SpeedTreeModel::CreateFromSpt("ymir work/tree/b1_baobab_rt.spt");
// 2. 森林多实例管理
speedtree::SpeedTreeForest forest;
forest.RegisterProperty(crc, "d:/ymir work/tree/b1_baobab.prt");
auto* instance = forest.CreateInstance(150.0f, 0.0f, 320.0f, crc, 45.0f, 1.0f);
// 3. 帧循环更新风力
forest.SetWindStrength(1.5f);
forest.Update(deltaTime);