首页 / luma.gl / API 文档

Sampler

先看结论

采样状态对象：过滤方式、寻址模式、mipmap 范围与各向异性都固化在里面。对象本身不可变，换参数就是换一个采样器。

最后验证 2026-11-03 · luma.gl 9.4 · 更新 2026-10-28 · 引用本文

device.createSampler(props) → Sampler

创建参数

参数	默认值	说明
`type`	`color-sampler`	`comparison-sampler` 用于深度比较采样
`addressModeU` / `addressModeV` / `addressModeW`	`clamp-to-edge`	`repeat`、`mirror-repeat`、`clamp-to-edge`
`magFilter`	`nearest`	放大时的过滤：`nearest` 或 `linear`
`minFilter`	`nearest`	缩小时的过滤
`mipmapFilter`	`none`	`none`、`nearest`、`linear`，需要纹理带 mipmap
`lodMinClamp` / `lodMaxClamp`	`0` / `32`	mipmap 层级的选择范围
`maxAnisotropy`	`1`	各向异性采样的最大值，需要后端支持
`compare`	`less-equal`	比较采样使用的比较函数

默认是最近邻加边缘钳制：放大后能看到方块状像素，UV 超出 0–1 时边缘被拉伸。需要平滑过渡时把两个过滤器都改成 linear。

成员

成员	说明
`id`	资源标识，便于调试输出
`props`	创建时归一化后的完整参数
`destroyed`	是否已释放
`destroy()`	释放底层采样器句柄

采样器没有读取参数的方法，需要参数就直接读 props。要改行为只能新建一个，再挂到纹理上。

两种使用方式

第一种是把采样器作为纹理的默认值；第二种是创建后替换，替换会比重新建纹理便宜得多。

const sampler = device.createSampler({
  minFilter: 'linear',
  magFilter: 'linear',
  mipmapFilter: 'none',
  addressModeU: 'repeat',
  addressModeV: 'repeat'
});

const texture = device.createTexture({
  width: 64,
  height: 64,
  format: 'rgba8unorm',
  sampler: sampler
});

/* 换成钳制模式：只需替换纹理上的采样器 */
texture.setSampler({
  minFilter: 'linear',
  magFilter: 'linear',
  mipmapFilter: 'none',
  addressModeU: 'clamp-to-edge',
  addressModeV: 'clamp-to-edge'
});

texture.setSampler 接受 Sampler 实例，也接受参数对象；传参数对象时会新建一个采样器再挂上去，省略的字段回到默认值。

后端差异

用法	WebGL 2	WebGPU
挂在纹理上	作为 `texParameter` 直接生效	作为纹理的默认采样器
作为独立绑定	被忽略，控制台给出提示	正常参与绑定组
比较采样	需要深度纹理格式	`comparison-sampler`

跨后端的代码不要依赖「把采样器单独绑进管线」这条路： WebGL 后端的实现只处理绑在纹理上的采样状态，单独绑定会在日志里提示被忽略，画面退回默认的最近邻采样。

采样器参数不全时按默认值补齐。只写 addressModeU 而漏掉过滤器，会得到 nearest 而不是上一份参数。需要保留其余设置时，把原有 props 展开再覆盖目标字段。

引用本文

经纬志（2026）。《Sampler》。https://www.jingweizhi.com/lumagl/api/sampler.html（访问日期 2026-11-03）。