L7 G-Device 引擎使用指南

[lzxue]

L7 使用 G-Device 引擎时的，一些 shader 写法和注意事项

G-Device 使用文档及 demo

https://observablehq.com/@antv/g-device-api#cell-417

WebGPU 教程

• WebGPU Shader language FAQ
• Graphics on the web and beyond with WebGPU

[lzxue]

纹理使用

因为 G-Device 做了 WebGL1、WebGL2 的兼容再使用纹理方法时，会进行转码

uniform sampler2D u_texture;

WebGL1 写法

outputColor = texture2D(u_texture, vec2(topU, topV));

WebGL2 写法

outputColor = texture(u_texture, vec2(topU, topV));

L7写法

outputColor = texture(SAMPLER_2D(u_texture), vec2(topU, topV));

增加与纹理定义的标识符 SAMPLER_2D

[lzxue]

GLSL标准Uniform Block(std140)布局规则

详细介绍

layout(std140) uniform test {
    float a;//offset为0
    float b;//offset为4
    vec3 f;//offset为16
    float s;//offset为28
};


layout(std140) uniform test {
    float a;//offset为0
    float b;//offset为4
    vec3 f;//offset为16
    vec3 s;//offset为32
};

struct st{
    float b;
};

layout(std140) uniform test {
    st c;//offset为0
    float d;//offset为16
};

layout(std140) uniform test{
    mat3x3 mat1;//offset为0
    mat3x3 mat;//offset为48
};

layout(std140) uniform test {
float a[3];//a[0] offset 0,a[1] offset 16,a[2] offset 32

};

layout(std140) uniform test{
    float a;//offset为0
    mat4x4 b;//offset为16
};

L7 shader 注意事项

std140 会影响 uniform 顺序，顺序不同会影响 buffer size

uniform

• 顺序推荐 Vec4 优先
• vec3 和 float 组合使用
• vec2 和 vec2 或者与两个float
• 不能组合成 4 位的放在最后
• 如果两个 vec3,第一vec3 就要补位 0 ，或者占位 float uniform
• vec3 使用vec4 存储

bad case

layout(std140) uniform commonUniforms {
  vec4 u_sourceColor; // offset为0
  float u_linearColor; // offset为4
  float u_topsurface; // offset为5
  float u_sidesurface; // offset为6  
  vec4 u_targetColor; // offset为8 
};

good case

layout(std140) uniform commonUniforms {
  vec4 u_sourceColor; // offset为0
   vec4 u_targetColor; // offset为4
  float u_linearColor; // offset为8
  float u_topsurface; // offset为9
  float u_sidesurface; // offset为10
};

[taiyuanhy]

sampler2D类型的uniform不要写到uniform Block中

[taiyuanhy]

layout(std140) uniform commonUniforms {
...
};
结尾一定要加分号，如果遇到修改之后程序卡死，有可能是shader在字符串处理时卡死了，我遇到过几次如果uniform后没有分号的话，就会卡死

[lzxue]

Maximum Attributes

L7 参与数据映射属性，通过attribute 设置，attribute 的数量是有限制的，WebGL 最低标准是 8个，chrome 支持 16 个

L7 attribute 分为三类

• 固定 attribute，如 ID、position，color
• 动态 attribute, 指在style 中参与数据映射的属性，如 opacity,storke,
• 自定义attribute 如 纹理坐标，不同图层个性化的

在使用需要考虑 最大个数，做的按需使用，按需分配空间。

[taiyuanhy]

两类uniform说明
除了自动生成的两组uniform(pick相关以及各种矩阵)之外，一般点，线，面的uniform分类两类，一类是通用的，一个是类自身的，注意在类自身的uniform中不要包含通用的uniform，例如点里的u_opacity。

[lzxue]

uniform 顺序问题

顺序问题出错一般会报，buffer small 错误

layout(std140) uniform commonUniforms {  // 必须在  #pragma include "projection" 前引入
 
    float u_opacity;
};

out vec2 v_texCoord;
#pragma include "projection"

[lzxue]

调试

SpectorJS shader 调试 Chrome 插件

SpectorJS 只有渲染过程才能捕捉相关信息，这里我们可以开启 l7 动画模式，这也画布会持续渲染。

scene.startAnimate();

[lzxue]

Framebuffer

2D / 3D 热力图在 WebGL 1 / 2 下均已验证。
需要注意的是在为 Framebuffer 创建 Texture 时需要指定 usage（默认为 SAMPLED）：

this.heatmapTexture = createTexture2D({
  width: Math.floor(width / 4),
  height: Math.floor(height / 4),
  wrapS: gl.CLAMP_TO_EDGE,
  wrapT: gl.CLAMP_TO_EDGE,
  min: gl.LINEAR,
  mag: gl.LINEAR,
  usage: TextureUsage.RENDER_TARGET, // 指定纹理用途，此处说明该纹理会被 attach 到 framebuffer 中
});

#2123