OpenLayers中WebGLPointsLayerRenderer自定义ShaderBuilder致片元着色器语法错误

1. 片元着色器语法错误原因分析 #

Uncaught Error: Fragment shader compilation failed: ERROR: 0:1: 'undefined' : syntax error 这个错误的核心原因是最终生成的片元着色器代码开头出现了undefined字符串，通常由以下场景导致：

• 使用ShaderBuilder构建着色器时，模板字符串中引用了未定义的变量（比如${someVar}中的someVar未声明）；
• 着色器模板字符串拼接时，某个片段返回了undefined（例如错误的函数调用返回值）；
• 未正确设置ShaderBuilder的片元着色器模板，传入了undefined而非合法的GLSL代码。

2. ShaderBuilder 与 WebGLPointsLayerRenderer 正确用法 #

核心规则 #

• ShaderBuilder是OpenLayers提供的着色器代码构建工具，需通过它声明varying、uniform、attribute变量，并编写顶点/片元着色器模板；
• WebGLPointsLayerRenderer作为自定义渲染器，必须在子类中实现createShader()方法返回配置好的ShaderBuilder实例，同时通过getAttributeLocations()映射数据源属性与着色器中的attribute变量。

关键步骤 #

1. 配置ShaderBuilder：声明变量、编写符合WebGL 1.0规范的GLSL代码；
2. 实现自定义Renderer：映射属性、关联ShaderBuilder；
3. 绑定数据源属性：确保图层数据源的feature属性与着色器中的attribute一一对应。

3. 修正方案与示例代码 #

示例：自定义圆形彩色点渲染 #

import {ShaderBuilder} from 'ol/webgl/ShaderBuilder.js';
import {VectorLayer} from 'ol/layer.js';
import {VectorSource} from 'ol/source.js';
import {Point} from 'ol/geom.js';
import {Feature} from 'ol/index.js';
import {WebGLPointsLayerRenderer} from 'ol/renderer/webgl/PointsLayer.js';

// 1. 配置ShaderBuilder
const shaderBuilder = new ShaderBuilder();
// 声明从顶点着色器传递到片元着色器的变量
shaderBuilder.addVarying('vec4', 'v_color');

// 顶点着色器：处理位置、大小和颜色传递
shaderBuilder.setVertexShader(`
  attribute vec2 a_position;
  attribute float a_size;
  attribute vec4 a_color;

  uniform mat4 u_projectionMatrix;
  uniform mat4 u_offsetScaleMatrix;
  uniform mat4 u_offsetRotateMatrix;

  void main() {
    vec4 offsetPosition = u_offsetRotateMatrix * vec4(a_position, 0.0, 1.0);
    gl_Position = u_projectionMatrix * (u_offsetScaleMatrix * offsetPosition);
    gl_PointSize = a_size;
    v_color = a_color;
  }
`);

// 片元着色器：实现圆形点效果，避免方形硬边缘
shaderBuilder.setFragmentShader(`
  precision mediump float;

  varying vec4 v_color;

  void main() {
    float dist = length(gl_PointCoord - vec2(0.5));
    if (dist > 0.5) {
      discard;
    }
    gl_FragColor = v_color;
  }
`);

// 2. 实现自定义WebGLPointsLayerRenderer
const customPointLayer = new VectorLayer({
  source: new VectorSource({
    features: [
      new Feature({
        geometry: new Point([0, 0]),
        size: 30, // 对应着色器中的a_size
        color: [255, 0, 0, 1] // 对应着色器中的a_color
      })
    ]
  }),
  renderer: class extends WebGLPointsLayerRenderer {
    createShader() {
      return shaderBuilder;
    }
    // 映射数据源属性到着色器attribute
    getAttributeLocations() {
      return {
        position: 'a_position',
        size: 'a_size',
        color: 'a_color'
      };
    }
  }
});

错误排查技巧 #

• 打开浏览器开发者工具的WebGL面板（Chrome：DevTools → More Tools → WebGL Inspector），查看最终生成的着色器代码，定位undefined出现的位置；
• 验证着色器模板字符串的所有变量引用均已正确定义，避免模板拼接时引入无效值；
• 不使用ShaderBuilder时，直接编写的着色器必须兼容OpenLayers内置uniforms（如u_projectionMatrix、u_offsetScaleMatrix），且语法符合GLSL 1.0标准。

内容的提问来源于stack exchange，提问作者Tarang Rathod