WebGL 小图贴上去全黑，怎样核对非二次幂纹理的采样完整性

WebGL1 的非二次幂纹理可以上传，但采样完整性受过滤与环绕规则限制。先检查是否仍使用需要 mipmap 的缩小过滤和 REPEAT，再按用途设置非 mipmap 过滤及 CLAMP_TO_EDGE，不能只以 texImage2D 无错误宣布贴图可用。

上传成功与采样成功分开

夹具生成3×5的原创不透明红色纹理，尺寸明确不是二次幂。默认参数绘制时中心像素为黑，随后将缩小过滤设为LINEAR，S与T环绕设为CLAMP_TO_EDGE，再画同一个三角形，中心应读到250、20、10、255。两轮图像数据没有变化，差别来自采样完整性条件。

不要只改一个参数就停止

仅设LINEAR可能仍留下REPEAT环绕，或者只改一轴环绕而另一轴仍不满足要求，问题会继续存在。实际引擎应把纹理用途、尺寸、过滤、环绕和是否生成mipmap共同记录。若效果需要重复铺贴，可考虑按需求改成合适资源或采用另一实现，不能无条件把所有纹理都强制夹边而改变美术效果。

这条限制必须标清版本

本题限定WebGL1，其规则不能机械推广到WebGL2。创建上下文时应记录getContext所用名称与gl.VERSION，不能只因为机器支持较新浏览器就认为当前页面已经使用WebGL2。附件同时保存着色器版本和renderer，所有绘制均本地完成，没有加载外部模型或贴图，也不解析glTF材质。

黑色结果还有别的来源

着色器未编译、纹理单元绑错、sampler指向其他单元、资源尚未上传也会产生错误或黑色画面。这里用最小固定着色器和中心采样隔离参数差异，readPixels只证明这一个像素和配置。现场应保留编译日志、getError与纹理状态，不把每次黑贴图都归到NPOT；软件后端通过也不等于实体显卡驱动稳定性已经验收。

以取样颜色验证而不是只数错误

不完整纹理的采样结果可能是规定的黑色，而不是每次都留下可被getError抓到的上传错误。附件同时读绘制像素和错误码，因此能区分参数未满足与上传调用本身失败。应用应检查sampler实际绑定的纹理对象，而非只看当前加载列表里有文件。纹理加载完成回调和采样完整性属于两项检查，缺一项都可能造成现场黑图。

下载并复现

下载原创HTML夹具、独立验证程序、本次执行记录和依赖与运行说明，放在同一目录。安装Playwright 1.58.0及其Chromium后运行 python verify.py；程序使用两个随机本地端口，自动关闭浏览器与服务，不请求外网或业务接口。

本次实际环境为Python 3.12.4、Playwright 1.58.0、Chromium 145.0.7632.6。Canvas2D或WebGL1页面API与像素读取；非指针输入、非实体GPU性能测量。断言已通过；完整事件和数值保留在执行记录，不能把它改名后当目标展项测量。

Canvas题限定2D上下文，WebGL题限定WebGL1；启动使用ANGLE SwiftShader软件后端参数，实际renderer可见对应执行记录。软件后端的像素结果不代表实体显卡性能、驱动稳定性或跨浏览器一致性。

继续核查与一级出处

基础背景见互动引擎怎么选？雷达/体感/触摸触发方式对比与选型清单。非二次幂采样规则与像素上传行对齐是独立条件，可继续用WebGL 贴图宽度是3像素就上传失败，怎样检查 UNPACK_ALIGNMENT取证；相关工程入口在专题与产品对接说明。

• WebGL1非二次幂纹理的环绕与缩小采样完整性：2026-10-24已联网读取一级来源；WebGL 1.0.3，2014-10-27；不把latest编辑草案当定稿。