首页 / luma.gl / API 文档

Texture

先看结论

纹理存放采样数据，也可以充当渲染目标。尺寸与格式在创建时固定，内容可以反复写入；采样参数挂在纹理自带的采样器上。

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

device.createTexture(props) → Texture

创建参数

参数	说明
`width` / `height`	像素尺寸，除一维纹理外都必须给出
`format`	`rgba8unorm`、`bgra8unorm`、`rgba16float`、`r8unorm`、`depth24plus` 等
`dimension`	`2d`（默认）、`1d`、`3d`、`2d-array`、`cube`、`cube-array`
`depth`	三维纹理或数组纹理的层数
`usage`	用途位掩码，见下表；默认同时允许采样、写入与作为渲染附件
`mipLevels`	mipmap 层数，默认 `1`
`samples`	多重采样数
`sampler`	`Sampler` 实例或采样参数，作为该纹理的默认采样器
`view`	默认纹理视图的配置
`data`	初始数据，已标记废弃，改为创建后调用 `writeData`

用途常量

常量	说明
`Texture.SAMPLE`	可在着色器中采样
`Texture.STORAGE`	可作为存储纹理读写
`Texture.RENDER`	可作为颜色或深度附件
`Texture.COPY_SRC`	可作为拷贝的来源
`Texture.COPY_DST`	可作为写入或拷贝的目标
`Texture.TEXTURE` / `Texture.RENDER_ATTACHMENT`	旧名，等价于 `SAMPLE` 与 `RENDER`

成员

成员	说明
`width` / `height` / `depth`	像素尺寸与层数
`format`	创建时的像素格式
`dimension` / `baseDimension`	维度类型，以及归属的基础维度
`mipLevels`	mipmap 层数
`samples`	采样数
`byteAlignment`	每行字节的对齐要求
`sampler`	默认采样器
`view`	默认纹理视图，可直接作为绑定值
`isReady` / `ready`	普通纹理恒为就绪；`DynamicTexture` 用它们表达加载状态
`updateTimestamp`	最近一次内容更新的时间戳

方法

方法	说明
`writeData(data, options)`	写入一段像素数据，可指定区域、mip 层与行对齐
`writeBuffer(buffer, options)`	从 GPU 缓冲区写入纹理
`readBuffer(options, buffer)`	把纹理内容读入缓冲区，再按需回读 CPU
`copyExternalImage(options)`	上传图片、视频帧等外部图像
`setSampler(sampler)`	替换默认采样器，立即生效
`createView(props)`	基于同一张纹理创建新的视图
`generateMipmapsWebGL()`	生成 mipmap，仅 WebGL
`clone(size)`	按相同参数复制一张纹理，不复制内容
`copyImageData(options)`	旧接口，等价于 `writeData`
`readDataAsync(options)`	旧接口，改为 `readBuffer` 配合缓冲区回读

上传程序生成的像素

const SIZE = 64;
const pixels = new Uint8Array(SIZE * SIZE * 4);

for (let y = 0; y < SIZE; y++) {
  for (let x = 0; x < SIZE; x++) {
    const i = (y * SIZE + x) * 4;
    const cell = ((x >> 3) + (y >> 3)) & 1;
    pixels[i] = cell ? 232 : 52;
    pixels[i + 1] = cell ? 186 : 118;
    pixels[i + 2] = cell ? 84 : 214;
    pixels[i + 3] = 255;
  }
}

const texture = device.createTexture({
  width: SIZE,
  height: SIZE,
  format: 'rgba8unorm',
  usage: Texture.SAMPLE | Texture.COPY_DST,
  sampler: {
    minFilter: 'linear',
    magFilter: 'linear',
    mipmapFilter: 'none',
    addressModeU: 'repeat',
    addressModeV: 'repeat'
  }
});

texture.writeData(pixels);

writeData 省略区域参数时按整张 mip 写入。数据按行紧密排列即可，后端需要的行对齐由它自行计算。

在着色器里采样

纹理通过 bindings 交给模型，键名与 GLSL 中的采样器 uniform 同名；采样器取值由 luma.gl 自动分配纹理单元，不需要手写 uniform1i。

const model = new Model(device, {
  vs: vsSource,
  fs: [
    '#version 300 es',
    'precision highp float;',
    'in vec2 vUV;',
    'uniform sampler2D uTexture;',
    'out vec4 fragColor;',
    'void main() {',
    '  fragColor = texture(uTexture, vUV);',
    '}'
  ].join('\n'),
  attributes: { positions: positions, uvs: uvs },
  bufferLayout: [
    { name: 'positions', stepMode: 'vertex', format: 'float32x3' },
    { name: 'uvs', stepMode: 'vertex', format: 'float32x2' }
  ],
  bindings: { uTexture: texture }
});

作为渲染目标

const color = device.createTexture({
  width: 256,
  height: 256,
  format: 'rgba8unorm',
  usage: Texture.SAMPLE | Texture.RENDER | Texture.COPY_DST,
  sampler: { minFilter: 'linear', magFilter: 'linear' }
});

const depth = device.createTexture({
  width: 256,
  height: 256,
  format: device.preferredDepthFormat,
  usage: Texture.RENDER
});

const fbo = device.createFramebuffer({
  width: 256,
  height: 256,
  colorAttachments: [color],
  depthStencilAttachment: depth
});

颜色附件要同时带 SAMPLE 与 RENDER：前者供下一趟采样，后者供本趟渲染。只给 RENDER 的纹理在 WebGPU 上不能再被采样。

尺寸一旦创建就不能改。需要换尺寸时用 clone({ width, height }) 建一张新纹理，内容不会自动带过去。逐帧更新的画面改用 DynamicTexture，它在尺寸变化时会自行重建。

引用本文

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