扩展指南如何为Compute-Shaders-Fluid-Dynamic引擎添加新Kernel反射式错误处理Dispatch校验【免费下载链接】Compute-Shaders-Fluid-Dynamic-Fluid Simulation Implementation in Compute Shaders using Unity3D项目地址: https://gitcode.com/gh_mirrors/co/Compute-Shaders-Fluid-Dynamic-Compute-Shaders-Fluid-Dynamic 是一个基于 Unity 3DCompute Shader实现的 2D 流体模拟引擎在 GPU 上完整实现了扩散、平流、压力投影等纳维-斯托克斯求解管线。本文用 5 步讲清楚如何为这套Compute Shader 流体模拟引擎添加你自己的 Kernel并深入解析它的反射式错误处理与Dispatch 校验机制让你扩展时不再踩坑 先了解引擎内置了哪些 Compute Shader整个引擎的 GPU 计算逻辑被拆分成 6 个 Compute Shader 文件都位于Assets/Shaders/Resources/FluidDynamic/目录下Compute Shader 文件职责Navier_Stokes.compute平流advection、散度计算、无散速度场投影Solvers.computeJacobi 迭代求解器扩散/泊松方程共用Boundary_Handling.compute四角 Neumann 边界 任意边界处理UserInput.compute鼠标/纹理注入染料与力场StructuredbufferToTexture.compute结构化缓冲区 → 纹理的可视化转换StructuredBufferUtility.compute缓冲区拷贝、清零等通用工具每个文件内的函数就是一个Kernel通过#pragma kernel 函数名暴露给 CPU。当你需要新的物理效果比如涡度增广、温度场、自定义求解器时就需要往里添加新 Kernel。作者已经在 Solvers.compute 的注释中预留了扩展提示比如实现 Gauss-Seidel 或 SOR 求解器来大幅提升性能。而添加 Kernel这件事的价值可以从另一个演示场景看出这个广袤大地雾效演示正是基于边界处理 Kernel 扩展而来——说明这套架构的扩展性是经过实战验证的。 快速上手5 步为引擎添加一个新 Kernel先看一下标准用法理解新增步骤在整个管线中的位置来自 2D 流体演示场景Assets/Scenes/2DFluid.unity的接线方式整个扩展流程只涉及 4 个文件官方给出的操作示意如下第 1 步在 Compute Shader 文件中编写 Kernel选择职责匹配的文件新求解器放Solvers.compute新输入方式放UserInput.compute按项目统一的注释风格编写#pragma kernel My_Solve [numthreads(16, 16, 1)] void My_Solve(uint3 id : SV_DispatchThreadID) { // 每个网格单元执行一次的计算逻辑 }两个要点#pragma kernel必须与函数名完全一致否则反射系统无法建立映射[numthreads]的组大小要能整除你的线程数默认仿真分辨率为 256是 16 的整数倍放心使用。第 2 步获取并保存 Kernel 句柄反射注册的关键这是引擎区别于普通 Demo 的核心设计。在 FluidSimulater.cs 中声明句柄成员然后在Initialize()里永远通过工具函数获取句柄private int _handle_my_kernel; // Initialize() 中 _handle_my_kernel ComputeShaderUtility.GetKernelHandle(SolverShader, My_Solve);为什么不能直接用FindKernel因为GetKernelHandle会把「句柄 → 名字」的映射写入一张全局字典见 ComputeShaderUtility.cs这张映射表正是后面日志报错、Dispatch 校验能说人话的基础。第 3 步管理 GPU 资源如果新 Kernel 需要额外的ComputeBuffer如 ping-pong 缓冲在 FluidGPUResources.cs 中声明并初始化/释放。引擎已有buffer_ping/buffer_pong两个辅助缓冲多数场景可直接复用避免自己重复创建。第 4 步在正确的时机设置参数引擎把参数按更新频率分成三档照抄这个习惯即可参数类型设置位置示例一次性不变的Initialize()分辨率、画布尺寸每帧变化Tick()在UpdateRuntimeKernelParameters中鼠标位置、时间每次调用前设置你的分发函数内部溶解系数、缓冲区绑定第 5 步分发 Kernel 并交给校验系统参考引擎中Advect函数的写法源码见 FluidSimulater.cs示意如下public void MyStep(ComputeBuffer buffer) { if (!IsValid()) return; // ① 先做有效性检查 SetBufferOnCommandList(sim_command_buffer, buffer, _my_buffer); sim_command_buffer.SetGlobalFloat(_my_factor, factor); // ② 统一走带校验的分发函数 DispatchComputeOnCommandBuffer(sim_command_buffer, SolverShader, _handle_my_kernel, simulation_dimension, simulation_dimension, 1); } 幕后机制一反射式错误处理如何帮你排查问题普通写法shader.FindKernel(名字)拼错时只会静默返回 -1问题在运行期才爆炸。本引擎的做法是在 ComputeShaderUtility.cs 里维护一张两级字典DictionaryComputeShader, Dictionaryint, string map_kernlesToNames;写入端GetKernelHandle在拿到句柄的同时把句柄 → 名字存进字典读取端GetKernelNameFromHandle在任何需要打印 Kernel 名的地方反查名字查不到才降级打印数字句柄。效果是所有 Dispatch 日志和错误信息里出现的都是Jacobi_Solve这样的可读名字而不是5。配合IsValid()的逐项检查Shader 引用、CommandBuffer、主相机是否就位你能在第一时间看到到底哪个 Compute Shader 没在 Inspector 里挂上。⚖️ 幕后机制二Dispatch 校验——线程数必须匹配组大小DispatchComputeOnCommandBuffer内部先调用CheckGetDispatchDimensions做两道硬性检查整除校验通过GetKernelThreadGroupSizes读出 Kernel 的[numthreads]组大小如 16×16×1若你期望的线程数不能被组大小整除立即LogError并Debug.Break()打断编辑器附带的错误信息里会写明 Shader 名和 Kernel 名——这就是反射映射表的价值GPU 利用率预警若三维线程总数低于 64打印警告提示你GPU 块利用率过低。以网格类 Kernel[numthreads(16,16,1)]为例默认simulation_dimension 256256 ÷ 16 16 组完美通过若你把分辨率改成 255编辑器会立刻断点报错而不是给你一个黑屏。工具类 Kernel如[numthreads(256,1,1)]的缓冲区拷贝则按simulation_dimension * simulation_dimension一维分发同样满足整除关系。⚠️ 扩展 Kernel 常见坑位速查清单坑表现解法Kernel 名与#pragma不一致句柄拿到但名字映射缺失日志打印数字严格保持两者一致线程数不整除组大小Debug.Break断点报错分辨率取 16 的倍数或调整[numthreads]忘记IsValid()检查Shader 未挂载时空引用崩溃函数第一行照抄引擎写法读写同一缓冲区造成竞态结果随机出错用 ping-pong 缓冲交替读写每帧重复创建缓冲区显存泄漏、性能骤降资源只在Initialize创建、Release释放按这 5 步走新 Kernel 从编写到跑通只需要改动 4 个文件一个.compute文件写逻辑、FluidSimulater.cs 注册句柄与分发、FluidGPUResources.cs 管资源、工具函数兜底校验。这套反射映射 整除校验的组合让扩展成本远低于裸写 Compute Shader 的踩坑成本值得作为你日后维护 GPU 代码的参考范式 【免费下载链接】Compute-Shaders-Fluid-Dynamic-Fluid Simulation Implementation in Compute Shaders using Unity3D项目地址: https://gitcode.com/gh_mirrors/co/Compute-Shaders-Fluid-Dynamic-创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 扩展指南：如何为Compute-Shaders-Fluid-Dynamic引擎添加新Kernel（反射式错误处理+Dispatch校验）
扩展指南如何为Compute-Shaders-Fluid-Dynamic引擎添加新Kernel反射式错误处理Dispatch校验【免费下载链接】Compute-Shaders-Fluid-Dynamic-Fluid Simulation Implementation in Compute Shaders using Unity3D项目地址: https://gitcode.com/gh_mirrors/co/Compute-Shaders-Fluid-Dynamic-Compute-Shaders-Fluid-Dynamic 是一个基于 Unity 3DCompute Shader实现的 2D 流体模拟引擎在 GPU 上完整实现了扩散、平流、压力投影等纳维-斯托克斯求解管线。本文用 5 步讲清楚如何为这套Compute Shader 流体模拟引擎添加你自己的 Kernel并深入解析它的反射式错误处理与Dispatch 校验机制让你扩展时不再踩坑 先了解引擎内置了哪些 Compute Shader整个引擎的 GPU 计算逻辑被拆分成 6 个 Compute Shader 文件都位于Assets/Shaders/Resources/FluidDynamic/目录下Compute Shader 文件职责Navier_Stokes.compute平流advection、散度计算、无散速度场投影Solvers.computeJacobi 迭代求解器扩散/泊松方程共用Boundary_Handling.compute四角 Neumann 边界 任意边界处理UserInput.compute鼠标/纹理注入染料与力场StructuredbufferToTexture.compute结构化缓冲区 → 纹理的可视化转换StructuredBufferUtility.compute缓冲区拷贝、清零等通用工具每个文件内的函数就是一个Kernel通过#pragma kernel 函数名暴露给 CPU。当你需要新的物理效果比如涡度增广、温度场、自定义求解器时就需要往里添加新 Kernel。作者已经在 Solvers.compute 的注释中预留了扩展提示比如实现 Gauss-Seidel 或 SOR 求解器来大幅提升性能。而添加 Kernel这件事的价值可以从另一个演示场景看出这个广袤大地雾效演示正是基于边界处理 Kernel 扩展而来——说明这套架构的扩展性是经过实战验证的。 快速上手5 步为引擎添加一个新 Kernel先看一下标准用法理解新增步骤在整个管线中的位置来自 2D 流体演示场景Assets/Scenes/2DFluid.unity的接线方式整个扩展流程只涉及 4 个文件官方给出的操作示意如下第 1 步在 Compute Shader 文件中编写 Kernel选择职责匹配的文件新求解器放Solvers.compute新输入方式放UserInput.compute按项目统一的注释风格编写#pragma kernel My_Solve [numthreads(16, 16, 1)] void My_Solve(uint3 id : SV_DispatchThreadID) { // 每个网格单元执行一次的计算逻辑 }两个要点#pragma kernel必须与函数名完全一致否则反射系统无法建立映射[numthreads]的组大小要能整除你的线程数默认仿真分辨率为 256是 16 的整数倍放心使用。第 2 步获取并保存 Kernel 句柄反射注册的关键这是引擎区别于普通 Demo 的核心设计。在 FluidSimulater.cs 中声明句柄成员然后在Initialize()里永远通过工具函数获取句柄private int _handle_my_kernel; // Initialize() 中 _handle_my_kernel ComputeShaderUtility.GetKernelHandle(SolverShader, My_Solve);为什么不能直接用FindKernel因为GetKernelHandle会把「句柄 → 名字」的映射写入一张全局字典见 ComputeShaderUtility.cs这张映射表正是后面日志报错、Dispatch 校验能说人话的基础。第 3 步管理 GPU 资源如果新 Kernel 需要额外的ComputeBuffer如 ping-pong 缓冲在 FluidGPUResources.cs 中声明并初始化/释放。引擎已有buffer_ping/buffer_pong两个辅助缓冲多数场景可直接复用避免自己重复创建。第 4 步在正确的时机设置参数引擎把参数按更新频率分成三档照抄这个习惯即可参数类型设置位置示例一次性不变的Initialize()分辨率、画布尺寸每帧变化Tick()在UpdateRuntimeKernelParameters中鼠标位置、时间每次调用前设置你的分发函数内部溶解系数、缓冲区绑定第 5 步分发 Kernel 并交给校验系统参考引擎中Advect函数的写法源码见 FluidSimulater.cs示意如下public void MyStep(ComputeBuffer buffer) { if (!IsValid()) return; // ① 先做有效性检查 SetBufferOnCommandList(sim_command_buffer, buffer, _my_buffer); sim_command_buffer.SetGlobalFloat(_my_factor, factor); // ② 统一走带校验的分发函数 DispatchComputeOnCommandBuffer(sim_command_buffer, SolverShader, _handle_my_kernel, simulation_dimension, simulation_dimension, 1); } 幕后机制一反射式错误处理如何帮你排查问题普通写法shader.FindKernel(名字)拼错时只会静默返回 -1问题在运行期才爆炸。本引擎的做法是在 ComputeShaderUtility.cs 里维护一张两级字典DictionaryComputeShader, Dictionaryint, string map_kernlesToNames;写入端GetKernelHandle在拿到句柄的同时把句柄 → 名字存进字典读取端GetKernelNameFromHandle在任何需要打印 Kernel 名的地方反查名字查不到才降级打印数字句柄。效果是所有 Dispatch 日志和错误信息里出现的都是Jacobi_Solve这样的可读名字而不是5。配合IsValid()的逐项检查Shader 引用、CommandBuffer、主相机是否就位你能在第一时间看到到底哪个 Compute Shader 没在 Inspector 里挂上。⚖️ 幕后机制二Dispatch 校验——线程数必须匹配组大小DispatchComputeOnCommandBuffer内部先调用CheckGetDispatchDimensions做两道硬性检查整除校验通过GetKernelThreadGroupSizes读出 Kernel 的[numthreads]组大小如 16×16×1若你期望的线程数不能被组大小整除立即LogError并Debug.Break()打断编辑器附带的错误信息里会写明 Shader 名和 Kernel 名——这就是反射映射表的价值GPU 利用率预警若三维线程总数低于 64打印警告提示你GPU 块利用率过低。以网格类 Kernel[numthreads(16,16,1)]为例默认simulation_dimension 256256 ÷ 16 16 组完美通过若你把分辨率改成 255编辑器会立刻断点报错而不是给你一个黑屏。工具类 Kernel如[numthreads(256,1,1)]的缓冲区拷贝则按simulation_dimension * simulation_dimension一维分发同样满足整除关系。⚠️ 扩展 Kernel 常见坑位速查清单坑表现解法Kernel 名与#pragma不一致句柄拿到但名字映射缺失日志打印数字严格保持两者一致线程数不整除组大小Debug.Break断点报错分辨率取 16 的倍数或调整[numthreads]忘记IsValid()检查Shader 未挂载时空引用崩溃函数第一行照抄引擎写法读写同一缓冲区造成竞态结果随机出错用 ping-pong 缓冲交替读写每帧重复创建缓冲区显存泄漏、性能骤降资源只在Initialize创建、Release释放按这 5 步走新 Kernel 从编写到跑通只需要改动 4 个文件一个.compute文件写逻辑、FluidSimulater.cs 注册句柄与分发、FluidGPUResources.cs 管资源、工具函数兜底校验。这套反射映射 整除校验的组合让扩展成本远低于裸写 Compute Shader 的踩坑成本值得作为你日后维护 GPU 代码的参考范式 【免费下载链接】Compute-Shaders-Fluid-Dynamic-Fluid Simulation Implementation in Compute Shaders using Unity3D项目地址: https://gitcode.com/gh_mirrors/co/Compute-Shaders-Fluid-Dynamic-创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考