diff --git a/.gitignore b/.gitignore index 02d0cd0..84d0fc6 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ CTestTestfile.cmake _deps /.vs /out +bin/ +out/ \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 25780fb..e17dc5b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,9 +3,11 @@ project(TestTracy) # 可用的选项：TRACY_ENABLE，TRACY_ON_DEMAND，TRACY_NO_BROADCAST，TRACY_NO_CODE_TRANSFER , ... # 在add_subdirectory之前设置选项 -option (TRACY_ENABLE "" ON) -option (TRACY_ON_DEMAND "" ON) +option (IS_TRACY_ENABLE "" ON) +option (IS_TRACY_ON_DEMAND "" ON) add_subdirectory ("thirdparty/tracy") #链接 `Tracy::TracyClient` 到你想要用Tracy进行性能分析的目标。 -add_executable(MyProject main.cpp) -target_link_libraries (MyProject PUBLIC Tracy::TracyClient) \ No newline at end of file +add_executable(TracyProject test.cpp) +target_link_libraries (TracyProject PUBLIC Tracy::TracyClient) + +add_subdirectory("unity_examples") \ No newline at end of file diff --git a/CMakeSettings.json b/CMakeSettings.json index 0c5fbf9..9204f06 100644 --- a/CMakeSettings.json +++ b/CMakeSettings.json @@ -10,18 +10,6 @@ "cmakeCommandArgs": "", "buildCommandArgs": "", "ctestCommandArgs": "" - }, - { - "name": "x64-Release", - "generator": "Ninja", - "configurationType": "RelWithDebInfo", - "buildRoot": "${projectDir}\\out\\build\\${name}", - "installRoot": "${projectDir}\\out\\install\\${name}", - "cmakeCommandArgs": "", - "buildCommandArgs": "", - "ctestCommandArgs": "", - "inheritEnvironments": [ "msvc_x64_x64" ], - "variables": [] } ] } \ No newline at end of file diff --git a/UNITY_INTEGRATION_GUIDE.md b/README.md similarity index 100% rename from UNITY_INTEGRATION_GUIDE.md rename to README.md diff --git a/README_TEST.md b/README_TEST.md deleted file mode 100644 index 3a5c502..0000000 --- a/README_TEST.md +++ /dev/null @@ -1,112 +0,0 @@ -# Tracy 性能测试代码说明 - -这个项目包含多个高性能计算测试用例，用于展示 Tracy 性能分析器的功能。 - -## 测试内容 - -### 1. 矩阵乘法 (Matrix Multiplication) -- 200x200 矩阵相乘 -- 展示计算密集型操作的性能 -- 三重循环，复杂度 O(n³) - -### 2. 快速排序 (Quick Sort) -- 对 100,000 个随机整数进行排序 -- 展示递归算法的性能特征 -- 平均复杂度 O(n log n) - -### 3. 质数计算 (Prime Numbers) -- 使用埃拉托斯特尼筛法 -- 计算 0-1,000,000 范围内的所有质数 -- 展示循环嵌套和内存访问模式 - -### 4. 蒙特卡罗π值计算 (Monte Carlo Pi) -- 使用随机采样方法估算π值 -- 10,000,000 次迭代 -- 展示随机数生成和条件判断的性能 - -### 5. 斐波那契数列 (Fibonacci) -- **递归方法**: fibonacci(35) - 展示递归调用的开销 -- **动态规划**: fibonacci(90) - 展示优化算法的性能差异 - -### 6. 向量点积 (Vector Dot Product) -- 10,000,000 维向量点积计算 -- 展示大规模线性代数运算 -- 内存访问密集型操作 - -### 7. 复杂数学运算 (Complex Math) -- sin, cos, tan, sqrt, log 等函数组合 -- 1,000,000 次迭代 -- 展示浮点运算性能 - -### 8. 内存密集型操作 (Memory Intensive) -- 创建 1000x1000 二维数组 -- 填充和遍历大量数据 -- 展示内存分配和访问模式 - -### 9. 多线程测试 (Multi-Threading) -- 8 个线程并行执行 -- 每个线程执行 50,000,000 次计算 -- 展示多线程性能和同步开销 - -## 如何使用 - -### 1. 编译项目 -```bash -# 在 Visual Studio 中打开项目 -# 选择 Release 配置以获得最佳性能测试结果 -# 构建项目 -``` - -### 2. 启动 Tracy Profiler -```bash -# 从 Tracy 仓库的 profiler 目录运行 -# 或使用预编译的 Tracy.exe -``` - -### 3. 运行测试程序 -```bash -# 运行 MyProject.exe -# Tracy Profiler 会自动连接（如果启用了 TRACY_ON_DEMAND） -``` - -### 4. 在 Tracy 中观察 -- 查看每个函数的执行时间 -- 比较递归 vs 动态规划的性能差异 -- 观察多线程的并行执行情况 -- 分析热点函数和瓶颈 - -## Tracy 宏说明 - -- `ZoneScoped`: 自动追踪整个函数的执行时间 -- `ZoneScopedN("名称")`: 追踪代码块并指定自定义名称 -- `FrameMark`: 标记帧边界，便于区分不同的测试轮次 - -## 性能优化建议 - -根据 Tracy 的分析结果，你可以： - -1. **识别热点**: 找出耗时最长的函数 -2. **优化算法**: 比较不同算法实现（如递归 vs 动态规划） -3. **并行化**: 识别可以并行化的计算 -4. **缓存优化**: 观察内存访问模式，优化数据结构 -5. **减少递归**: 递归调用会带来额外开销 - -## 预期结果 - -在 Tracy Profiler 中，你应该能够看到： - -- **矩阵乘法**: 相对较长的执行时间，CPU 密集 -- **递归斐波那契**: 大量重复的函数调用（可视化调用树） -- **动态规划斐波那契**: 单次执行，线性时间 -- **多线程**: 8 个并行执行的线程，清晰的时间线 -- **质数计算**: 循环密集，但相对高效 -- **蒙特卡罗**: 稳定的执行时间，随机数生成开销 - -## 提示 - -- 使用 Release 配置编译可以获得更接近实际应用的性能数据 -- 多次运行测试可以在 Tracy 中观察性能的一致性 -- 尝试修改参数（矩阵大小、迭代次数等）观察性能变化 -- 使用 Tracy 的统计功能分析函数调用次数和平均执行时间 - - diff --git a/main.cpp b/test.cpp similarity index 99% rename from main.cpp rename to test.cpp index 6ed808c..cedd23b 100644 --- a/main.cpp +++ b/test.cpp @@ -175,7 +175,7 @@ void memoryIntensiveOperation(size_t size) { // 填充数据 for (size_t i = 0; i < size; i++) { for (size_t j = 0; j < size; j++) { - bigArray[i][j] = i * j; + bigArray[i][j] = static_cast(i * j); } } diff --git a/unity_examples/CMakeLists.txt b/unity_examples/CMakeLists.txt index f882f7a..1b24188 100644 --- a/unity_examples/CMakeLists.txt +++ b/unity_examples/CMakeLists.txt @@ -11,40 +11,45 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON) # 配置选项 # ============================================ -option(TRACY_ENABLE "启用 Tracy 性能分析" ON) -option(TRACY_ON_DEMAND "Tracy 按需分析模式" ON) -option(TRACY_NO_EXIT "Tracy 不在退出时断开连接" OFF) -option(TRACY_NO_BROADCAST "Tracy 不广播发现消息" OFF) -option(TRACY_ONLY_LOCALHOST "Tracy 仅允许本地连接" OFF) +option(IS_TRACY_ENABLE "启用 Tracy 性能分析" ON) +option(IS_TRACY_ON_DEMAND "Tracy 按需分析模式" ON) +option(IS_TRACY_NO_EXIT "Tracy 不在退出时断开连接" OFF) +option(IS_TRACY_NO_BROADCAST "Tracy 不广播发现消息" OFF) +option(IS_TRACY_ONLY_LOCALHOST "Tracy 仅允许本地连接" OFF) +option(IS_ADVANCED_ZONE_MANAGEMENT "启用Tracy管理器类" ON) # ============================================ # Tracy 配置 # ============================================ -if(TRACY_ENABLE) +if(IS_TRACY_ENABLE) add_definitions(-DTRACY_ENABLE) message(STATUS "Tracy 性能分析: 启用") else() message(STATUS "Tracy 性能分析: 禁用") endif() -if(TRACY_ON_DEMAND) +if(IS_TRACY_ON_DEMAND) add_definitions(-DTRACY_ON_DEMAND) message(STATUS "Tracy 按需模式: 启用") endif() -if(TRACY_NO_EXIT) +if(IS_TRACY_NO_EXIT) add_definitions(-DTRACY_NO_EXIT) endif() -if(TRACY_NO_BROADCAST) +if(IS_TRACY_NO_BROADCAST) add_definitions(-DTRACY_NO_BROADCAST) endif() -if(TRACY_ONLY_LOCALHOST) +if(IS_TRACY_ONLY_LOCALHOST) add_definitions(-DTRACY_ONLY_LOCALHOST) endif() +if(IS_ADVANCED_ZONE_MANAGEMENT) + add_definitions(-DADVANCED_ZONE_MANAGEMENT) +endif() + # ============================================ # Tracy 路径配置 # ============================================ @@ -251,8 +256,8 @@ message(STATUS "项目版本: ${PROJECT_VERSION}") message(STATUS "C++ 标准: ${CMAKE_CXX_STANDARD}") message(STATUS "构建类型: ${CMAKE_BUILD_TYPE}") message(STATUS "编译器: ${CMAKE_CXX_COMPILER_ID}") -message(STATUS "Tracy 启用: ${TRACY_ENABLE}") -message(STATUS "Tracy 按需模式: ${TRACY_ON_DEMAND}") +message(STATUS "Tracy 启用: ${IS_TRACY_ENABLE}") +message(STATUS "Tracy 按需模式: ${IS_TRACY_ON_DEMAND}") message(STATUS "========================================") # ============================================ diff --git a/unity_examples/QUICKSTART.md b/unity_examples/QUICKSTART.md deleted file mode 100644 index 739083a..0000000 --- a/unity_examples/QUICKSTART.md +++ /dev/null @@ -1,494 +0,0 @@ -# Tracy Unity 集成快速开始指南 - -本指南将帮助你快速将 Tracy 性能分析器集成到 Unity 项目中。 - ---- - -## 🚀 快速开始（5 分钟集成） - -### 步骤 1: 准备 Tracy - -1. 克隆或下载 Tracy 仓库： -```bash -git clone https://github.com/wolfpld/tracy.git -``` - -2. （可选）编译 Tracy Profiler 工具： -```bash -cd tracy/profiler -# Windows: 使用 Visual Studio 打开并编译 -# macOS/Linux: -cmake -B build -DCMAKE_BUILD_TYPE=Release -cmake --build build -``` - -### 步骤 2: 编译 Unity Plugin - -#### Windows (使用 CMake + Visual Studio) - -```powershell -# 在 unity_examples 目录下 -mkdir build -cd build - -# 配置（修改 TRACY_ROOT 路径指向你的 tracy 目录） -cmake .. -G "Visual Studio 17 2022" -A x64 ^ - -DTRACY_ROOT="D:/path/to/tracy" ^ - -DTRACY_ENABLE=ON ^ - -DTRACY_ON_DEMAND=ON - -# 编译 -cmake --build . --config Release -``` - -编译完成后，DLL 文件在 `build/Unity/Plugins/x86_64/UnityTracyPlugin.dll` - -#### macOS - -```bash -# 在 unity_examples 目录下 -mkdir build && cd build - -# 配置 -cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DTRACY_ROOT="/path/to/tracy" \ - -DTRACY_ENABLE=ON \ - -DTRACY_ON_DEMAND=ON - -# 编译 -make -j8 -``` - -编译完成后，动态库在 `build/Unity/Plugins/macOS/UnityTracyPlugin.dylib` - -#### Linux - -```bash -# 在 unity_examples 目录下 -mkdir build && cd build - -# 配置 -cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DTRACY_ROOT="/path/to/tracy" \ - -DTRACY_ENABLE=ON \ - -DTRACY_ON_DEMAND=ON - -# 编译 -make -j8 -``` - -编译完成后，动态库在 `build/Unity/Plugins/Linux/x86_64/UnityTracyPlugin.so` - -### 步骤 3: 集成到 Unity 项目 - -1. **复制 Plugin 文件** - -将编译好的 Plugin 复制到 Unity 项目： - -``` -YourUnityProject/ -└── Assets/ - └── Plugins/ - ├── x86_64/ - │ └── UnityTracyPlugin.dll # Windows - ├── macOS/ - │ └── UnityTracyPlugin.dylib # macOS - └── Linux/ - └── x86_64/ - └── UnityTracyPlugin.so # Linux -``` - -2. **复制 C# 脚本** - -将以下文件复制到 Unity 项目： - -``` -YourUnityProject/ -└── Assets/ - └── Scripts/ - └── Tracy/ - ├── TracyWrapper.cs # Tracy C# API - ├── TracyManager.cs # Tracy 管理器 - └── TracyExamples.cs # 使用示例（可选） -``` - -3. **配置 Plugin 导入设置** - -在 Unity Editor 中： -- 选择 `UnityTracyPlugin.dll`（或 .dylib/.so） -- 在 Inspector 中设置平台： - - Windows: 勾选 `x86_64` - - macOS: 勾选 `macOS` - - Linux: 勾选 `Linux x86_64` - -### 步骤 4: 在场景中使用 - -1. **添加 TracyManager** - -在你的主场景中： -- 创建空 GameObject，命名为 "TracyManager" -- 添加 `TracyManager` 组件 -- 在 Inspector 中配置选项 - -2. **在代码中使用 Tracy** - -```csharp -using UnityEngine; -using TracyProfiler; - -public class MyGameScript : MonoBehaviour -{ - void Update() - { - // 方式 1: 使用 using 语句（推荐） - using (Tracy.Zone("MyGameScript.Update")) - { - DoSomething(); - } - - // 方式 2: 手动开始/结束 - Tracy.BeginZone("CustomZone"); - DoSomethingElse(); - Tracy.EndZone(); - - // 绘制数值 - Tracy.Plot("Enemy Count", enemyCount); - - // 发送消息 - if (playerDied) - { - Tracy.Message("Player died"); - } - } - - void DoSomething() - { - using (Tracy.Zone("DoSomething")) - { - // 你的代码 - } - } -} -``` - -### 步骤 5: 启动 Tracy Profiler 并连接 - -1. **启动 Tracy Profiler** - -```bash -# Windows -Tracy.exe - -# macOS/Linux -./Tracy -``` - -2. **运行 Unity 游戏** - -在 Unity Editor 中按 Play，或运行构建的可执行文件。 - -3. **连接到 Tracy** - -Tracy Profiler 会自动发现本地网络中的 Tracy 客户端，点击连接即可开始分析。 - ---- - -## 📊 使用 Tracy 分析性能 - -### 查看性能数据 - -Tracy Profiler 界面主要区域： - -1. **时间线视图** - - 显示所有 Zone 的执行时间 - - 颜色表示不同的调用栈深度 - - 可以缩放和平移 - -2. **统计视图** - - 函数调用次数 - - 总耗时、平均耗时、最小/最大耗时 - - 排序和筛选功能 - -3. **帧视图** - - 查看每帧的性能 - - 识别帧率波动 - - 帧时间分布 - -4. **Plot 视图** - - 查看 `Tracy.Plot()` 绘制的数值曲线 - - 实时监控变量变化 - -### 常用快捷键 - -- `鼠标滚轮`: 缩放时间线 -- `鼠标中键拖拽`: 平移时间线 -- `鼠标左键`: 选择 Zone 查看详情 -- `Ctrl + F`: 搜索函数 -- `Ctrl + Z`: 放大到选中的 Zone - ---- - -## 🔧 常见问题排查 - -### 问题 1: DLL 加载失败 - -**错误信息**: `DllNotFoundException: UnityTracyPlugin` - -**解决方案**: -1. 确认 DLL 文件在正确的目录 -2. 检查 Plugin Import Settings 的平台配置 -3. 确认 DLL 架构与 Unity 项目匹配（x64/x86） -4. Windows: 检查是否缺少 `vcruntime140.dll`（安装 Visual C++ Redistributable） - -### 问题 2: Tracy Profiler 无法连接 - -**症状**: Tracy Profiler 中看不到 Unity 应用 - -**解决方案**: -1. 确认防火墙允许 TCP 端口 8086 -2. 检查 `TRACY_ON_DEMAND` 宏是否正确定义 -3. 确认 `Tracy.Initialize()` 已被调用 -4. 检查 Unity Console 是否有 Tracy 初始化消息 - -```csharp -// 在 Unity Console 应该看到: -// [Tracy] 性能分析器已初始化 -``` - -### 问题 3: 性能数据不显示 - -**症状**: Tracy 已连接，但看不到任何 Zone - -**解决方案**: -1. 确认代码中使用了 `Tracy.Zone()` 或 `ZoneScoped` -2. 确认 `Tracy.MarkFrame()` 在每帧被调用 -3. 检查是否定义了 `TRACY_ENABLE` 编译符号 -4. 在 Unity Editor 中，确认 Tracy Manager 的 "Enable On Start" 已勾选 - -### 问题 4: 编译错误 - -**常见编译错误**: - -1. **找不到 Tracy.hpp** - ``` - fatal error: tracy/Tracy.hpp: No such file or directory - ``` - 解决: 检查 `TRACY_ROOT` 路径是否正确 - -2. **链接错误 (Windows)** - ``` - error LNK2019: unresolved external symbol - ``` - 解决: 确认链接了 `ws2_32.lib` 和 `dbghelp.lib` - -3. **链接错误 (Linux)** - ``` - undefined reference to `pthread_create' - ``` - 解决: 添加 `-lpthread -ldl` 链接选项 - -### 问题 5: Android/iOS 构建问题 - -**Android**: -1. 使用 Android NDK 编译 -2. 确保为所有需要的 ABI 编译（armeabi-v7a, arm64-v8a） -3. 将 `.so` 文件放在 `Assets/Plugins/Android/libs/{ABI}/` - -**iOS**: -1. 编译为静态库（.a） -2. 在 Unity Build Settings 中设置 "Target SDK" 为 "Device SDK" -3. 确保代码签名正确 - ---- - -## 🎯 最佳实践 - -### 1. Zone 命名规范 - -```csharp -// ✅ 好的命名 - 清晰、描述性 -using (Tracy.Zone("PlayerController.Move")) -using (Tracy.Zone("AI.UpdatePathfinding")) -using (Tracy.Zone("Render.DrawTerrain")) - -// ❌ 不好的命名 - 模糊、无意义 -using (Tracy.Zone("Function1")) -using (Tracy.Zone("Update")) -using (Tracy.Zone("Test")) -``` - -### 2. 适度使用 Zone - -```csharp -void Update() -{ - // ✅ 追踪主要的逻辑块 - using (Tracy.Zone("Update")) - { - using (Tracy.Zone("ProcessInput")) - { - ProcessInput(); // 追踪大块逻辑 - } - - UpdateGameLogic(); // 内部有自己的 Zone - } -} - -// ❌ 过度追踪会增加开销 -void BadExample() -{ - for (int i = 0; i < 10000; i++) - { - using (Tracy.Zone($"Iteration {i}")) // 太多 Zone！ - { - DoSomething(); - } - } -} -``` - -### 3. 使用条件编译 - -```csharp -// 在生产构建中禁用细粒度追踪 -#if TRACY_ENABLE - using (Tracy.Zone("DetailedAnalysis")) - { - // 详细的性能分析代码 - } -#endif -``` - -### 4. 监控关键指标 - -```csharp -void LateUpdate() -{ - // 监控帧率 - Tracy.Plot("FPS", 1.0f / Time.deltaTime); - - // 监控内存 - Tracy.Plot("Memory (MB)", GC.GetTotalMemory(false) / 1024.0 / 1024.0); - - // 监控对象计数 - Tracy.Plot("Enemy Count", enemies.Count); - Tracy.Plot("Active Particles", particleSystem.particleCount); - - // 监控物理 - Tracy.Plot("Rigidbodies", FindObjectsOfType().Length); -} -``` - -### 5. 多线程命名 - -```csharp -using System.Threading; - -void WorkerThread() -{ - Tracy.SetThreadName("Worker Thread"); - - while (running) - { - using (Tracy.Zone("WorkerThread.Process")) - { - ProcessData(); - } - } -} -``` - ---- - -## 📚 进阶主题 - -### 自定义构建配置 - -在 Unity 项目中创建 `link.xml` 防止代码剥离： - -```xml - - - - - -``` - -### 持久化性能数据 - -Tracy 支持保存性能数据到文件： - -1. 在 Tracy Profiler 中，点击 "Save trace" -2. 选择保存位置（.tracy 文件） -3. 之后可以用 Tracy Profiler 打开查看 - -### 集成到 CI/CD - -可以在自动化测试中使用 Tracy： - -```csharp -public class PerformanceTest -{ - [Test] - public void TestPerformance() - { - Tracy.Initialize(); - - using (Tracy.Zone("PerformanceTest")) - { - // 运行性能测试 - RunGameLoop(100); // 运行 100 帧 - } - - Tracy.Shutdown(); - - // 分析结果... - } -} -``` - ---- - -## 🔗 资源链接 - -- [Tracy 官方仓库](https://github.com/wolfpld/tracy) -- [Tracy 官方手册](https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf) -- [Unity Native Plugin 文档](https://docs.unity3d.com/Manual/NativePlugins.html) -- 本项目的完整文档: `UNITY_INTEGRATION_GUIDE.md` - ---- - -## 💡 技巧和提示 - -1. **使用 Release 构建进行性能测试** - - Debug 构建会有大量额外开销 - - 在 Unity 中创建专门的 "Profiling" 构建配置 - -2. **关闭 V-Sync 测试真实性能** - - V-Sync 会限制帧率 - - 在 Project Settings > Quality 中关闭 - -3. **使用 Tracy 的统计功能** - - 查看函数调用次数 - - 识别被频繁调用的函数 - -4. **比较不同实现** - - 使用 Tracy 比较算法性能 - - A/B 测试优化效果 - -5. **定期保存 Trace 文件** - - 记录性能基准 - - 跟踪性能变化趋势 - ---- - -## 🎉 完成！ - -现在你已经成功将 Tracy 集成到 Unity 项目中了！ - -开始使用 Tracy 分析你的游戏性能，找出瓶颈，优化代码吧！ - -如有问题，请参考完整文档 `UNITY_INTEGRATION_GUIDE.md` 或访问 Tracy 官方仓库。 - diff --git a/unity_examples/README.md b/unity_examples/README.md deleted file mode 100644 index b1b0101..0000000 --- a/unity_examples/README.md +++ /dev/null @@ -1,484 +0,0 @@ -# Tracy Unity 集成示例 - -本目录包含将 Tracy 性能分析器集成到 Unity 项目的完整示例和工具。 - -## 📁 文件结构 - -``` -unity_examples/ -├── README.md # 本文件 - 项目概述 -├── QUICKSTART.md # 5分钟快速开始指南 ⭐ 从这里开始！ -├── CMakeLists.txt # CMake 构建配置 -├── SimplifiedPlugin.cpp # Tracy Unity Plugin C++ 实现 -├── TracyWrapper.cs # Tracy C# API 封装 -├── TracyManager.cs # Tracy 管理器组件 -└── TracyExamples.cs # 使用示例和最佳实践 -``` - -## 🚀 快速开始 - -### 新手用户 - -如果你是第一次使用，请按以下顺序阅读： - -1. **[QUICKSTART.md](QUICKSTART.md)** - 5分钟快速集成指南 -2. **[TracyExamples.cs](TracyExamples.cs)** - 查看代码示例 -3. **[../UNITY_INTEGRATION_GUIDE.md](../UNITY_INTEGRATION_GUIDE.md)** - 完整的集成文档 - -### 有经验的用户 - -快速集成步骤： - -```bash -# 1. 编译 Plugin -mkdir build && cd build -cmake .. -DTRACY_ROOT="/path/to/tracy" -DCMAKE_BUILD_TYPE=Release -cmake --build . --config Release - -# 2. 复制文件到 Unity 项目 -cp build/Unity/Plugins/* YourUnityProject/Assets/Plugins/ -cp *.cs YourUnityProject/Assets/Scripts/Tracy/ - -# 3. 在 Unity 场景中添加 TracyManager 组件 - -# 4. 运行 Tracy Profiler 并连接 -``` - -## 📦 文件说明 - -### C++ Plugin 相关 - -#### `SimplifiedPlugin.cpp` -Tracy Unity Native Plugin 的 C++ 实现。 - -**主要功能**: -- 初始化/关闭 Tracy -- 创建性能追踪 Zone -- 绘制实时数值 -- 发送消息和日志 -- 线程命名 - -**导出函数**: -```cpp -TracyInit() // 初始化 -TracyShutdown() // 关闭 -TracyFrameMark() // 标记帧边界 -TracyZoneBegin(name) // 开始 Zone -TracyZoneEnd() // 结束 Zone -TracyPlotValue(name, v) // 绘制数值 -TracyMessage(msg) // 发送消息 -TracySetThreadName(name) // 设置线程名 -``` - -**编译要求**: -- C++17 -- Tracy 源代码 -- Windows: Visual Studio 2019+ -- macOS: Xcode 12+ -- Linux: GCC 9+ 或 Clang 10+ - -#### `CMakeLists.txt` -跨平台 CMake 构建配置。 - -**支持平台**: -- ✅ Windows (x64) -- ✅ macOS (Intel/Apple Silicon) -- ✅ Linux (x64) -- ✅ Android (armeabi-v7a, arm64-v8a) -- ✅ iOS (arm64) - -**配置选项**: -```cmake --DTRACY_ENABLE=ON # 启用 Tracy --DTRACY_ON_DEMAND=ON # 按需分析模式 --DTRACY_ROOT=path # Tracy 根目录 -``` - -### C# 脚本相关 - -#### `TracyWrapper.cs` -Tracy 的 C# API 封装，提供简洁易用的接口。 - -**核心 API**: -```csharp -// 初始化 -Tracy.Initialize() - -// 性能追踪 (推荐使用 using 语句) -using (Tracy.Zone("FunctionName")) -{ - // 要追踪的代码 -} - -// 手动管理 Zone -Tracy.BeginZone("CustomZone") -// ... 代码 ... -Tracy.EndZone() - -// 绘制实时数值 -Tracy.Plot("FPS", fps) -Tracy.Plot("Memory", memoryMB) - -// 发送消息 -Tracy.Message("重要事件发生") - -// 设置线程名 -Tracy.SetThreadName("Worker Thread") - -// 标记帧边界 -Tracy.MarkFrame() -``` - -**特性**: -- 使用 `IDisposable` 自动管理 Zone 生命周期 -- 条件编译支持（`TRACY_ENABLE`） -- 零开销（禁用时） -- 线程安全 - -#### `TracyManager.cs` -Unity 组件，负责 Tracy 的初始化和自动化监控。 - -**功能**: -- 自动初始化 Tracy -- 每帧自动标记帧边界 -- 自动监控系统指标: - - 帧率 (FPS) - - 帧时间 - - 内存使用 - - 渲染统计 - - 物理对象数量 - -**使用方法**: -1. 在场景中创建空 GameObject -2. 添加 `TracyManager` 组件 -3. 配置 Inspector 中的选项 -4. 运行游戏 - -**Inspector 选项**: -- `Enable On Start`: 启动时自动初始化 -- `Mark Frames`: 每帧自动标记 -- `Monitor Frame Rate`: 监控帧率 -- `Monitor Memory`: 监控内存 -- `Monitor Rendering`: 监控渲染 -- `Monitor Physics`: 监控物理 - -#### `TracyExamples.cs` -完整的使用示例和最佳实践。 - -**包含示例**: -1. ✅ 基础 Zone 使用 -2. ✅ 计算密集型操作追踪 -3. ✅ 重度计算测试 -4. ✅ 对象池管理 -5. ✅ 协程性能追踪 -6. ✅ 自定义数据绘制 -7. ✅ 条件性能追踪 - -**交互功能**: -- 按 `Space` 键: 执行重度计算 -- 按 `R` 键: 重置对象池 -- 按 `T` 键: 运行性能测试 - -## 🎯 使用场景 - -### 1. 游戏开发性能优化 - -```csharp -public class GameController : MonoBehaviour -{ - void Update() - { - using (Tracy.Zone("GameController.Update")) - { - using (Tracy.Zone("Update AI")) - { - UpdateAI(); - } - - using (Tracy.Zone("Update Physics")) - { - UpdatePhysics(); - } - - using (Tracy.Zone("Update Rendering")) - { - UpdateRendering(); - } - } - } -} -``` - -### 2. 资源加载分析 - -```csharp -IEnumerator LoadScene() -{ - using (Tracy.Zone("Load Scene")) - { - using (Tracy.Zone("Load Assets")) - { - yield return LoadAssets(); - } - - using (Tracy.Zone("Initialize Scene")) - { - InitializeScene(); - } - - Tracy.Message("Scene loaded successfully"); - } -} -``` - -### 3. AI 系统性能追踪 - -```csharp -public class AIManager : MonoBehaviour -{ - void Update() - { - using (Tracy.Zone("AI Manager")) - { - foreach (var agent in agents) - { - using (Tracy.Zone($"AI Agent {agent.id}")) - { - agent.UpdateBehavior(); - } - } - - Tracy.Plot("Active AI Agents", agents.Count); - } - } -} -``` - -### 4. 网络同步分析 - -```csharp -void OnNetworkUpdate() -{ - using (Tracy.Zone("Network Update")) - { - using (Tracy.Zone("Receive Packets")) - { - ReceivePackets(); - } - - using (Tracy.Zone("Process Messages")) - { - ProcessMessages(); - } - - using (Tracy.Zone("Send Updates")) - { - SendUpdates(); - } - - Tracy.Plot("Network Latency (ms)", latency); - Tracy.Plot("Packet Loss (%)", packetLoss); - } -} -``` - -### 5. 渲染管线优化 - -```csharp -void OnPreRender() -{ - using (Tracy.Zone("Pre-Render")) - { - using (Tracy.Zone("Culling")) - { - PerformCulling(); - } - - using (Tracy.Zone("Sort Render Queue")) - { - SortRenderQueue(); - } - - Tracy.Plot("Visible Objects", visibleCount); - Tracy.Plot("Draw Calls", drawCalls); - } -} -``` - -## 🔧 平台特定说明 - -### Windows - -**依赖**: -- Visual Studio 2019 或更高版本 -- Windows SDK -- vcruntime140.dll (Visual C++ Redistributable) - -**编译**: -```powershell -cmake -B build -G "Visual Studio 17 2022" -A x64 -cmake --build build --config Release -``` - -**输出**: `build/Unity/Plugins/x86_64/UnityTracyPlugin.dll` - -### macOS - -**依赖**: -- Xcode Command Line Tools -- CMake 3.15+ - -**编译**: -```bash -cmake -B build -DCMAKE_BUILD_TYPE=Release -cmake --build build -``` - -**输出**: `build/Unity/Plugins/macOS/UnityTracyPlugin.dylib` - -**注意**: Apple Silicon (M1/M2) 和 Intel 需要分别编译 - -### Linux - -**依赖**: -- GCC 9+ 或 Clang 10+ -- pthread, dl - -**编译**: -```bash -cmake -B build -DCMAKE_BUILD_TYPE=Release -cmake --build build -``` - -**输出**: `build/Unity/Plugins/Linux/x86_64/UnityTracyPlugin.so` - -### Android - -**依赖**: -- Android NDK r21+ -- CMake 3.15+ - -**编译**: -```bash -# ARM64 -cmake -B build-android-arm64 \ - -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \ - -DANDROID_ABI=arm64-v8a \ - -DANDROID_PLATFORM=android-21 - -# ARMv7 -cmake -B build-android-armv7 \ - -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \ - -DANDROID_ABI=armeabi-v7a \ - -DANDROID_PLATFORM=android-21 -``` - -### iOS - -**依赖**: -- Xcode 12+ -- iOS SDK - -**编译**: -```bash -cmake -B build-ios \ - -DCMAKE_SYSTEM_NAME=iOS \ - -DCMAKE_OSX_ARCHITECTURES=arm64 \ - -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0 -``` - -**注意**: iOS 需要静态库（.a）而不是动态库 - -## 📊 性能影响 - -### Tracy 开销 - -| 配置 | 每 Zone 开销 | 内存开销 | 网络带宽 | -|------|-------------|---------|---------| -| 禁用 (Release) | 0 ns | 0 MB | 0 | -| 启用 (On-Demand, 未连接) | ~20 ns | ~1 MB | 0 | -| 启用 (已连接) | ~50 ns | ~10 MB | ~1 Mbps | - -### 建议 - -- ✅ 在 Debug/Development 构建中启用 -- ✅ 追踪主要逻辑块（毫秒级） -- ⚠️ 避免追踪微小操作（微秒级） -- ⚠️ 避免在紧密循环中创建 Zone -- ❌ 不建议在 Release 构建中启用细粒度追踪 - -## 🐛 故障排除 - -### 常见问题 - -详细的故障排除指南请参考 [QUICKSTART.md](QUICKSTART.md#常见问题排查) - -**快速检查清单**: - -- [ ] DLL 文件在正确的 Plugins 目录 -- [ ] Plugin Import Settings 配置正确 -- [ ] Tracy Profiler 正在运行 -- [ ] 防火墙允许端口 8086 -- [ ] `Tracy.Initialize()` 已被调用 -- [ ] Unity Console 显示初始化消息 -- [ ] 代码中使用了 `Tracy.Zone()` 或 `ZoneScoped` -- [ ] `TracyManager` 组件已添加到场景 - -### 获取帮助 - -如果遇到问题： - -1. 查看 [QUICKSTART.md](QUICKSTART.md) 的故障排除章节 -2. 查看 [完整集成指南](../UNITY_INTEGRATION_GUIDE.md) -3. 查看 [Tracy 官方文档](https://github.com/wolfpld/tracy) -4. 检查 Unity Console 的错误消息 - -## 📚 相关资源 - -### 文档 - -- [快速开始指南](QUICKSTART.md) - 5分钟集成 -- [完整集成指南](../UNITY_INTEGRATION_GUIDE.md) - 详细文档 -- [Tracy 官方手册](https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf) - PDF - -### 链接 - -- [Tracy GitHub](https://github.com/wolfpld/tracy) - 官方仓库 -- [Tracy 演示视频](https://www.youtube.com/watch?v=fB5B46lbapc) - YouTube -- [Unity Native Plugins](https://docs.unity3d.com/Manual/NativePlugins.html) - 官方文档 - -### 示例项目 - -本目录中的示例展示了： -- 基本的 Zone 使用 -- 性能数据绘制 -- 协程追踪 -- 多线程支持 -- 最佳实践 - -## 🤝 贡献 - -欢迎改进和建议！ - -如果你有更好的实现方式或发现了问题，请： -1. 修改代码 -2. 测试你的更改 -3. 分享你的改进 - -## 📄 许可证 - -- Tracy: BSD 3-Clause License -- 本示例代码: MIT License - -## 🎉 开始使用 - -现在你已经了解了整体结构，可以开始集成了！ - -**下一步**: 打开 [QUICKSTART.md](QUICKSTART.md) 开始 5 分钟快速集成！ - ---- - -**祝你使用愉快！** 🚀 - -如有任何问题，欢迎查阅文档或在社区寻求帮助。 - diff --git a/unity_examples/SimplifiedPlugin.cpp b/unity_examples/SimplifiedPlugin.cpp index 107dfee..a02cc13 100644 --- a/unity_examples/SimplifiedPlugin.cpp +++ b/unity_examples/SimplifiedPlugin.cpp @@ -1,24 +1,29 @@ /* - * Tracy Unity Plugin - 简化版实现 + * Tracy Unity Plugin - Simplified Implementation * - * 这是一个简化的 Tracy Unity Plugin 实现 - * 用于演示如何将 Tracy 集成到 Unity Native Plugin 中 + * This is a simplified Tracy Unity Plugin implementation + * demonstrating how to integrate Tracy into Unity Native Plugin * - * 编译说明: - * Windows: cl /LD /MD SimplifiedPlugin.cpp /I"path/to/tracy/public" ws2_32.lib dbghelp.lib - * macOS: clang++ -shared -fPIC SimplifiedPlugin.cpp -I"path/to/tracy/public" -o libUnityTracyPlugin.dylib - * Linux: g++ -shared -fPIC SimplifiedPlugin.cpp -I"path/to/tracy/public" -o libUnityTracyPlugin.so -lpthread -ldl + * Build instructions: + * Windows: Use CMake (see CMakeLists.txt) + * macOS: Use CMake (see CMakeLists.txt) + * Linux: Use CMake (see CMakeLists.txt) */ -// 定义 Tracy 启用标志 -#define TRACY_ENABLE -#define TRACY_ON_DEMAND +#pragma warning(disable:4100) #include "tracy/Tracy.hpp" #include #include -// 平台特定的导出定义 +#ifdef ADVANCED_ZONE_MANAGEMENT +#include +#include +#include +#include +#endif + +// Platform specific export definition #if defined(_WIN32) || defined(_WIN64) #define UNITY_PLUGIN_EXPORT __declspec(dllexport) #elif defined(__APPLE__) || defined(__linux__) @@ -27,139 +32,166 @@ #define UNITY_PLUGIN_EXPORT #endif -// C 导出函数（Unity 需要 C 链接） -extern "C" { - -/** - * 初始化 Tracy - * Unity C# 调用: [DllImport] private static extern void TracyInit(); - */ -UNITY_PLUGIN_EXPORT void TracyInit() -{ - // Tracy 会自动初始化，这里可以添加额外的初始化逻辑 - // 例如：设置采样率、配置选项等 +// Simple Zone Manager for basic Zone tracking +#ifndef ADVANCED_ZONE_MANAGEMENT +namespace { + struct SimpleZone { + const char* name; + int64_t startTime; + }; + + struct ThreadZones { + std::stack zones; + }; + + std::unordered_map g_threadZones; + std::mutex g_zonesMutex; } +#endif -/** - * 关闭 Tracy - * Unity C# 调用: [DllImport] private static extern void TracyShutdown(); - */ -UNITY_PLUGIN_EXPORT void TracyShutdown() +// C export functions (Unity requires C linkage) +extern "C" { - // Tracy 会在程序退出时自动清理 - // 这里可以添加自定义的清理逻辑 -} - -/** - * 标记帧边界 - * Unity C# 调用: [DllImport] private static extern void TracyFrameMark(); - */ -UNITY_PLUGIN_EXPORT void TracyFrameMark() -{ - FrameMark; -} - -/** - * 绘制数值 - * Unity C# 调用: [DllImport] private static extern void TracyPlotValue(string name, double value); - */ -UNITY_PLUGIN_EXPORT void TracyPlotValue(const char* name, double value) -{ - if (name != nullptr) + /** + * Initialize Tracy + * Unity C# call: [DllImport] private static extern void TracyInit(); + */ + UNITY_PLUGIN_EXPORT void TracyInit() { - TracyPlot(name, value); + // Tracy initializes automatically, additional initialization logic can be added here } -} -/** - * 发送消息 - * Unity C# 调用: [DllImport] private static extern void TracyMessage(string message); - */ -UNITY_PLUGIN_EXPORT void TracyMessage(const char* message) -{ - if (message != nullptr) + /** + * Shutdown Tracy + * Unity C# call: [DllImport] private static extern void TracyShutdown(); + */ + UNITY_PLUGIN_EXPORT void TracyShutdown() { - TracyMessage(message, std::strlen(message)); +#ifndef ADVANCED_ZONE_MANAGEMENT + std::lock_guard lock(g_zonesMutex); + g_threadZones.clear(); +#endif } -} -/** - * 设置线程名称 - * Unity C# 调用: [DllImport] private static extern void TracySetThreadName(string name); - */ -UNITY_PLUGIN_EXPORT void TracySetThreadName(const char* name) -{ - if (name != nullptr) + /** + * Mark frame boundary + * Unity C# call: [DllImport] private static extern void TracyFrameMark(); + */ + UNITY_PLUGIN_EXPORT void TracyFrameMark() { - tracy::SetThreadName(name); + FrameMark; } -} -/** - * 开始一个命名的 Zone - * Unity C# 调用: [DllImport] private static extern void TracyZoneBegin(string name); - * - * 注意: 这是简化版实现，实际使用中需要更复杂的 Zone 管理 - */ -UNITY_PLUGIN_EXPORT void TracyZoneBegin(const char* name) -{ - if (name != nullptr) + /** + * Plot value + * Unity C# call: [DllImport] private static extern void TracyPlotValue(string name, double value); + */ + UNITY_PLUGIN_EXPORT void TracyPlotValue(const char* name, double value) { - // 简化版: 使用动态分配的 Zone - // 实际应用中需要管理 Zone 的生命周期 + if (name != nullptr) + { + TracyPlot(name, value); + } + } + + /** + * Send message + * Unity C# call: [DllImport] private static extern void TracySendMessage(string message); + */ + UNITY_PLUGIN_EXPORT void TracySendMessage(const char* message) + { + if (message != nullptr) + { + TracyMessage(message, std::strlen(message)); + } + } + + /** + * Set thread name + * Unity C# call: [DllImport] private static extern void TracySetThreadName(string name); + */ + UNITY_PLUGIN_EXPORT void TracySetThreadName(const char* name) + { + if (name != nullptr) + { + tracy::SetThreadName(name); + } + } + + /** + * Begin a named Zone + * Unity C# call: [DllImport] private static extern void TracyZoneBegin(string name); + * + * Note: This is a simplified implementation. For production use, consider using + * ADVANCED_ZONE_MANAGEMENT or a different Zone management approach. + */ + UNITY_PLUGIN_EXPORT void TracyZoneBegin(const char* name) + { +#ifndef ADVANCED_ZONE_MANAGEMENT + if (name != nullptr) + { + std::lock_guard lock(g_zonesMutex); + auto threadId = std::this_thread::get_id(); + + SimpleZone zone; + zone.name = name; + zone.startTime = tracy::GetTime(); + + g_threadZones[threadId].zones.push(zone); + + // Send zone begin event to Tracy + TracyMessageL(name); + } +#endif + } + + /** + * End current Zone + * Unity C# call: [DllImport] private static extern void TracyZoneEnd(); + */ + UNITY_PLUGIN_EXPORT void TracyZoneEnd() + { +#ifndef ADVANCED_ZONE_MANAGEMENT + std::lock_guard lock(g_zonesMutex); + auto threadId = std::this_thread::get_id(); + auto it = g_threadZones.find(threadId); - // 方案1: 使用全局 Zone 栈（简单但不支持多线程） - // 方案2: 使用线程局部存储（复杂但支持多线程） - // 方案3: 返回 Zone ID 给 C#，让 C# 管理（推荐） - - // 这里使用宏创建一个 Zone - // 注意：这只是示例，实际使用需要更好的管理方式 - ZoneName(name, std::strlen(name)); + if (it != g_threadZones.end() && !it->second.zones.empty()) + { + it->second.zones.pop(); + } +#endif } -} -/** - * 结束当前 Zone - * Unity C# 调用: [DllImport] private static extern void TracyZoneEnd(); - */ -UNITY_PLUGIN_EXPORT void TracyZoneEnd() -{ - // 简化版: 与 ZoneBegin 配对使用 - // 实际应用中需要管理 Zone 的结束 -} + /** + * Unity plugin lifecycle function - called on load + */ + UNITY_PLUGIN_EXPORT void UnityPluginLoad() + { + // Optional: perform initialization when plugin loads + } -/** - * Unity 插件生命周期函数 - 加载时调用 - */ -UNITY_PLUGIN_EXPORT void UnityPluginLoad() -{ - // 可选：在插件加载时执行初始化 -} - -/** - * Unity 插件生命周期函数 - 卸载时调用 - */ -UNITY_PLUGIN_EXPORT void UnityPluginUnload() -{ - // 可选：在插件卸载时执行清理 -} + /** + * Unity plugin lifecycle function - called on unload + */ + UNITY_PLUGIN_EXPORT void UnityPluginUnload() + { + // Optional: perform cleanup when plugin unloads + TracyShutdown(); + } } // extern "C" /* - * 高级实现示例 - Zone 管理 + * Advanced Implementation Example - Zone Management * - * 下面是一个更完善的 Zone 管理实现示例 - * 可以根据需要扩展 + * Below is a more complete Zone management implementation example + * Can be extended as needed */ #ifdef ADVANCED_ZONE_MANAGEMENT -#include -#include -#include - -// Zone 管理器（线程安全） +// Zone Manager (Thread-safe) class ZoneManager { private: @@ -179,10 +211,10 @@ public: auto threadId = std::this_thread::get_id(); auto& zones = threadZones[threadId].zones; - // 创建源位置信息 + // Create source location info static const tracy::SourceLocationData loc{name, function, file, line, 0}; - // 创建 Zone（注意：需要在堆上分配） + // Create Zone (note: must be heap allocated) auto* zone = new tracy::ScopedZone(&loc, true); zones.push(zone); } @@ -211,7 +243,7 @@ public: if (it != threadZones.end()) { - // 清理所有未结束的 Zone + // Clean up all unfinished Zones while (!it->second.zones.empty()) { delete it->second.zones.top(); @@ -222,7 +254,7 @@ public: } }; -// 全局 Zone 管理器实例 +// Global Zone Manager instance static ZoneManager g_zoneManager; extern "C" { @@ -247,41 +279,18 @@ UNITY_PLUGIN_EXPORT void TracyClearThreadZones() #endif // ADVANCED_ZONE_MANAGEMENT /* - * 编译和部署说明： + * Build and Deployment Instructions: * - * 1. Windows (Visual Studio): - * - 创建 DLL 项目 - * - 添加 Tracy 源文件: tracy/public/TracyClient.cpp - * - 包含目录: tracy/public - * - 链接库: ws2_32.lib dbghelp.lib - * - 输出: UnityTracyPlugin.dll + * Use CMake for all platforms (see CMakeLists.txt) * - * 2. macOS: - * clang++ -std=c++17 -shared -fPIC \ - * SimplifiedPlugin.cpp \ - * tracy/public/TracyClient.cpp \ - * -I tracy/public \ - * -DTRACY_ENABLE -DTRACY_ON_DEMAND \ - * -o libUnityTracyPlugin.dylib + * Quick build: + * 1. mkdir build && cd build + * 2. cmake .. -DTRACY_ROOT="/path/to/tracy" + * 3. cmake --build . --config Release * - * 3. Linux: - * g++ -std=c++17 -shared -fPIC \ - * SimplifiedPlugin.cpp \ - * tracy/public/TracyClient.cpp \ - * -I tracy/public \ - * -DTRACY_ENABLE -DTRACY_ON_DEMAND \ - * -lpthread -ldl \ - * -o libUnityTracyPlugin.so - * - * 4. Android (NDK): - * 在 Android.mk 或 CMakeLists.txt 中配置 - * - * 5. iOS: - * 使用 Xcode 编译为静态库 (.a) - * - * 部署到 Unity: - * - 将编译好的库文件复制到 Unity 项目的 Assets/Plugins/ 目录 - * - 根据平台放置在相应的子目录中 - * - 配置 Plugin Import Settings 以匹配目标平台 + * Deploy to Unity: + * - Copy compiled library to Unity project Assets/Plugins/ directory + * - Place in appropriate subdirectory based on platform + * - Configure Plugin Import Settings to match target platform */ diff --git a/unity_examples/TracyWrapper.cs b/unity_examples/TracyWrapper.cs index cc88ee2..cb77e64 100644 --- a/unity_examples/TracyWrapper.cs +++ b/unity_examples/TracyWrapper.cs @@ -31,7 +31,7 @@ namespace TracyProfiler private static extern void TracyPlotValue(string name, double value); [DllImport(DLL_NAME, CallingConvention = CallingConvention.Cdecl)] - private static extern void TracyMessage(string message); + private static extern void TracySendMessage(string message); [DllImport(DLL_NAME, CallingConvention = CallingConvention.Cdecl)] private static extern void TracySetThreadName(string name); @@ -154,7 +154,7 @@ namespace TracyProfiler public static void Message(string message) { if (!s_initialized || !s_enabled) return; - TracyMessage(message); + TracySendMessage(message); } ///