已查出的兼容性问题整理

[jk20012001]

精度相关

lowp: 2位指数5位尾数, 1/32 = 0.03125
mediump: 10位尾数 1 / 1024 = 0.0009765625 ≈ 0.001

1. 除了微信, 字节的其他小平台, 8888shadowmap float计算精度都有问题, 是贴图采样出来只有小数点后4位的样子，是因为sampler默认是lowp的，所以所有的数据贴图都必须在sampler前加highp来定义（已解决）
2. vivo小平台, ubo数据标mediump的精度很低, 导致debug view单选数据对EPSILON的equalf失效, 改成EPSILON_LOWP就可以了（已解决） https://github.com/cocos/3d-tasks/issues/15562
3. iPhoneX/11 + 字节小平台 https://github.com/cocos/3d-tasks/issues/12650
   部分华为麒麟海思芯片(P30, P40等) 的原生GLES或WebGL中，浮点格式贴图读写精度不足导致shadowBias效果出错 https://github.com/cocos/3d-tasks/issues/13330
   可以强制使用Packing, 或在每个sampler2D shadowmap的定义处(包括函数传参)都要加highp, 或直接shader头部加precisioni highp sampler2D（已解决）
4. 安卓原生平台, Oppo RenoZ这种机子vs输出ps的项必须指定一个精度, 否则就会传错误的值(1.0传下去变成了0.0) https://github.com/cocos/3d-tasks/issues/10955

---

5. 安卓+webgl平台, ps中结构体所有成员的精度只能是mediump, 无法提升, 用到position之类对精度要求高的数据要注意进行pack/unpack, 使用宏方式来定义和赋值（已解决）, 表现形式可能是高光或阴影有异常 https://github.com/cocos-creator/3d-tasks/issues/10538 https://github.com/cocos/3d-tasks/issues/13091
   有时候normal精度不足也会造成错误, 可能需要对normal也做额外的补偿处理

---

6. 安卓Chrome/UC浏览器会出现深度比较精度随时间抽风的问题 https://github.com/cocos-creator/3d-tasks/issues/9205 https://github.com/cocos-creator/3d-tasks/issues/10915 https://github.com/cocos-creator/3d-tasks/issues/10924

---

7. 16bit float支持大值域导致数据精度更差，对于normalized value而言，最好还是用Normalized类型，但16bit下没有UN或SN格式，此时就使用8＋8 packing来解决，精度会比16bit float格式更好 https://github.com/cocos-creator/3d-tasks/issues/9540

---

8. iPhoneX/11 + 字节小平台, v_clip_pos精度为mediump, 无法提升 https://github.com/cocos/3d-tasks/issues/12655
   要特别注意这种需要齐次除的数据, 一定要在ps里除, 尤其是透视投影

---

指令相关

1. 注意不同平台下支持不一样, 安卓有些是不支持textureLod采样的,在代码中就只能用textureBias来替换, 这会造成 PBR反射的粗糙度不同（已知问题） https://github.com/cocos-creator/3d-tasks/issues/10492

---

2. Vulkan下mod函数的被除数不能大于100 https://github.com/cocos-creator/3d-tasks/issues/9858
   https://github.com/cocos-creator/engine/pull/9847/files
   关联--https://github.com/cocos-creator/3d-tasks/issues/9858
   shader里面pseudoRandom vk不兼容，具体是vk的shader不兼容此处mod的输入值，需要找一个替代写法才行
   

---

3. oppo r11的step和大于小于写法, 只有两种执行是正确的:
   [1] 大于小于用来判断常量:
   if (xxx <= UBO.clipvalue)是错的, if (xxx <= 128)是对的, 大于小于只能拿来判断常量, 判断变量或者UBO常量就错
   [2] step不能直接&&:
   step可以判断任何变量和常量, 但step不能写成if (step && step),要写成a = step; b= step; if(a && b)
   结论是: 推荐使用step代替大于小于, 但多个step不要出现在一个语句中
   也可能要分Shader, VS用> <, PS用step会兼容性更好
   https://github.com/cocos-creator/3d-tasks/issues/10249 PS中的用法
   https://github.com/cocos-creator/3d-tasks/issues/9022 VS中的用法, 3.4.1好像又正确了

---

4. oppo vivo等机型，或小米6安卓8系统下，在循环中如果出现break / continue / return等动态控制语句，可能导致crash，如https://github.com/cocos/3d-tasks/issues/10779
   所以说在不是必须要动态分支的地方，尽量使用宏展开的unroll形式，就算写成for也不要有上述三个语句。

---

5. 动态分支if内不能修改if外超过vec4大小的变量 https://github.com/cocos/3d-tasks/issues/9236

---

6. pow需要注意, 指数不可以为0, 否则在安卓上可能出现一些异常的值导致锯齿, 黑线 亮线之类的

---

贴图及采样相关

1. WebGL2.0不支持DS格式的图以linear方式采样, 否则会全黑 OpenGL ES: What extensions allows depth textures to be filterable? KhronosGroup/OpenGL-API#84

---

2. iOS WebGL, 字节百度等小平台下, 如果图片带有A通道但没有开Alpha Blend, 也没有正常的透贴discard, WebGL底层在Shader采样贴图时会自动返回(RGB*A, 1)的值, 所以不可以在不开透贴和半透的情况下使用这样的图, 正常透贴是可以支持的
3. iOS 微信小游戏，如果图片带有A通道（比如RGBE png），底层在Shader采样贴图时会自动将RGB处理成一些奇怪的值导致RGBE解码的颜色错误，a通道全填1就好了，不知如何解决 https://github.com/cocos/3d-tasks/issues/13050
4. iOS WebGL, 如果开启Blend, ps的a通道输出0就会混出奇怪的颜色

---

5. M1芯片mac, 回读R32F格式的贴图会失败, 只能换成R32G32B32F

---

函数参数

1. 极少数机型 PS中不支持函数输出一个结构体(out StandardSurface s)这样的写法 , Unity中是改为结构体中的每项单独out之后编译的
   https://github.com/cocos-creator/3d-tasks/issues/10131#issuecomment-979582484
   https://github.com/cocos-creator/3d-tasks/issues/9303

2. 注意函数参数中需要输出结构体的情况，如果函数A(out StructType s)、B(inout vec3 xx)和C(inout StructType s)，在A中调用B(s.test)和C(s)，都会造成兼容性问题，原生GL上会无法正常写入test项（WebGL可能是正常的）。反之A(inout StructType s)、B(out vec3 xx)和C(out StructType s)也是不行的，out必须严格对应所有调用处的out，inout必须严格对应inout
   为了统一，所有和结构体及其内部单项数据相关的传参都应给inout参数

3. 注意函数参数中使用分支条件修改out参数的时候, 在mac上可能造成强制初始化
   不一定会修改的传参也都应给inout参数

4. 也要注意函数参数中需要输出mat4的情况, 如CSMGetLevel(out mat4), 要改成输出4个vec4(out vec4, out vec4, out vec4, out vec4), 否则对out mat4参数赋值的语句放在for或if中会导致crash (如oppo r11st) https://github.com/cocos/3d-tasks/issues/12596

5. WebGL1.0不支持带参数的宏的写法，只能使用#pragma define使用预先处理的字符串展开

---

其他

1. 百度平台 + oppo findx或一加机器上, 在vs的main函数中直接输出varying变量, 在ps中拿到的就是无效值(无理数), 如果main函数调用另一个函数输出该变量就可以, 相当于必须包一层函数调用, 不知道是否是gl编译器的bug https://github.com/cocos/3d-tasks/issues/13200#issuecomment-1198820757
2. Vulkan + 安卓平台, 镜像法线标记在ps中访问可能会是接近0的值, 导致乘出来的bitangent为零向量, normalize之后变成无理数, 这里使用专门的判断使其必定是-1或1 https://github.com/cocos/3d-tasks/issues/14121
3. 小米6 + Vulkan，某些Surface函数如SurfacesVertexModifyLocalPos直接返回xxx.xyz会导致crash，比如强行转换为vec3(xxx.xyz)才可以
4. 小米 ＋ GLES后端原生，如果先用默认RT，然后切其他RT，最后又切回默认RT的话（比如多相机的情景），可能导致Clear Depth出错，不管指定什么值，Clear进去的都是最小值 https://github.com/cocos/3d-tasks/issues/14077
5. 微信 + WebGL2，shadowmap无法clear为正确的值，貌似都会clear为camera的clear color

---

硬件能力

1. UC浏览器(所有硬件平台) 不支持Feature.INSTANCED_ARRAYS, 所以有半透明物体开启Instancing是无效的, 这会导致半透绘制顺序的变更, 因为半透物体先画Instancing的, 再画非Instancing https://github.com/cocos/3d-tasks/issues/14165
2. 老苹果(SE 7等) 支持的maxFragmentUniformVectors比较少, 会导致加了CSM的一堆uniform之后编译报错, 在3.6.0添加了对此能力检测的支持 [optimization] Split csm ubo v3.6.0 cocos/cocos-engine#12072
   iOS 15.4.1报的maxVertexUniformVectors也很少, 导致骨骼使用的uniform越界, 自动计算之后可以修复 [Bug] fix maxJoints calculate error cocos/cocos-engine#13174
   微信平台报的maxVertexUniformVectors很多但其实不能用, 会导致骨骼动画都画不出来, 通过写死root.ts中自动计算的Count为256可以检查是否正常
3. Oppo小平台的IB只能支持16bit，所以模型顶点数不可以超64k

---

引擎相关代码

1. shadowUBO在shader中include了但是没有使用(场景没开阴影), 但也必须在引擎中updateUBO, 否则在vivo7p上就会crash, 如https://github.com/cocos/3d-tasks/issues/10779

---

问题集查询

已知待查验: surface shader场景(同时开instancing和两盏局部光才)会导致vivox7p crash
test-case的鸭子场景material-upgrade, 鸭子使用legacy/toon.effect的话会在华为H60-L02的安卓原生上无光照
小游戏平台已知问题收集: https://github.com/cocos/2d-tasks/issues/2581