PyQtGraph 0.13.x 版本不支持为 GLMeshItem 自定义 GLSL 着色器；该功能仅在 0.14.0 开发版中正式引入。直接复用社区旧代码会导致着色器编译成功但渲染无响应，根本原因在于属性绑定机制与 OpenGL 上下文管理的版本差异。
pyqtgraph 0.13.x 版本不支持为 glmeshitem 自定义 glsl 着色器；该功能仅在 0.14.0 开发版中正式引入。直接复用社区旧代码会导致着色器编译成功但渲染无响应，根本原因在于属性绑定机制与 opengl 上下文管理的版本差异。
在 PyQtGraph 中为 GLMeshItem 配置自定义着色器是一个常见却极易踩坑的操作。许多开发者（包括提问者）在尝试复现 GitHub 论坛或早期 PR 中的示例代码时发现：着色器对象能成功创建、ID 可被正确获取（如 print("Shader program ID:", self.shader.program()) 输出非零值），但模型始终以默认白色/灰色渲染，完全无视着色逻辑——甚至连最基础的颜色映射（如法线转 RGB）也不生效。
问题本质并非 GLSL 语法错误或 OpenGL 状态异常，而是PyQtGraph 的着色器架构存在重大版本断层：
- ✅ PyQtGraph ≤ 0.13.7（稳定版）：
GLMeshItem硬编码使用内置着色器管线，其顶点属性（a_position,a_normal,a_color）由内部MeshData绑定逻辑直接写死到固定位置（如glVertexAttribPointer(0, ...)），完全忽略用户传入的shader=参数。此时即使调用gl.shaders.Shaders.append(...)，该着色器也不会被GLMeshItem.paint()调用。 - ✅ PyQtGraph ≥ 0.14.0.dev0（开发版）：重构了
GLMeshItem的渲染流程，正式支持通过shader=指定自定义ShaderProgram，并动态解析in属性位置（glGetAttribLocation），实现与用户着色器的语义对齐。
这也解释了为何调试输出呈现“反直觉”现象：
# 使用自定义 shader='hilight' → 返回有效 location（2, 0, 1） # 使用内置 shader='edgeHilight' → 全部返回 -1（未启用 attribute binding）
因为 edgeHilight 是预编译的内置着色器，其属性由 C++ 层硬编码绑定；而你的 hilight 着色器虽被注册，但在 0.13.7 中根本不会进入 attribute 绑定流程——glGetAttribLocation 返回的只是编译后程序中符号的位置，不代表它已被实际启用。
✅ 正确解决方案（二选一）
方案一：升级至支持版本（推荐）
# 卸载旧版 pip uninstall pyqtgraph -y # 安装最新开发版（含完整自定义 shader 支持） pip install git+https://github.com/pyqtgraph/pyqtgraph.git@master # 验证版本 python -c "import pyqtgraph as pg; print(pg.__version__)" # 应输出类似 '0.14.0.dev0'
升级后，以下代码即可正常工作：
import pyqtgraph.opengl as gl
from pyqtgraph.opengl.shaders import ShaderProgram, VertexShader, FragmentShader
# 注册自定义着色器（注意：必须在创建 GLMeshItem 前完成）
gl.shaders.Shaders.append(
ShaderProgram('hilight', [
VertexShader("""
#version 120
uniform mat4 u_mvp;
attribute vec3 a_position;
attribute vec3 a_normal;
varying vec3 v_normal;
void main() {
v_normal = normalize(a_normal); // 使用传入法线，非 gl_Normal（已弃用）
gl_Position = u_mvp * vec4(a_position, 1.0);
}
"""),
FragmentShader("""
#version 120
varying vec3 v_normal;
void main() {
vec3 color = (v_normal + 1.0) * 0.5; // 法线可视化
gl_FragColor = vec4(color, 1.0);
}
""")
])
)
# 创建 mesh 并指定 shader
mesh = gl.GLMeshItem(
meshdata=mesh_data,
shader='hilight', # ✅ 现在真正生效
smooth=True,
drawFaces=True,
computeNormals=True
)
⚠️ 注意事项：
- GLSL 版本需匹配（PyQtGraph 默认使用
#version 120，避免#version 330 core）；- 禁用已废弃的
gl_NormalMatrix和gl_Normal，改用显式传入的a_normal；- 确保
MeshData包含vertexes、faces和normals（可通过mesh_data.setFaceColors(...)或computeNormals=True生成）。
方案二：降级兼容（仅限无法升级环境）
若受制于生产环境约束无法升级 PyQtGraph，则放弃自定义着色器，转而使用内置 shader 或 Python 层后处理：
# 使用内置高亮效果（无需修改版本） mesh = gl.GLMeshItem(meshdata=mesh_data, shader='edgeHilight') # 或手动修改 MeshData 的 face colors 实现类似效果 normals = mesh_data.faceNormals() colors = (normals + 1.0) / 2.0 # 归一化到 [0,1] colors = np.hstack([colors, np.ones((len(colors), 1))]) # 添加 alpha mesh_data.setFaceColors(colors) mesh = gl.GLMeshItem(meshdata=mesh_data, smooth=True, drawFaces=True)
总结
PyQtGraph 的着色器支持不是“开箱即用”的平滑特性，而是随版本演进逐步开放的底层能力。在工程实践中，务必确认所用版本的官方文档（pyqtgraph.readthedocs.io）与 GitHub Release Notes。对于实时数据可视化、科学仿真等高性能场景，建议主动采用 0.14.0+ 版本，并结合 pyqtgraph.opengl.GLViewWidget 与 GLMeshItem 构建可扩展的 GPU 渲染管线——这不仅是解决一个着色器问题，更是为后续集成几何着色器（wireframe）、计算着色器（GPGPU 数据处理）打下坚实基础。
