TextureLoader
Quick answer
TextureLoader loads images asynchronously and returns a Texture ready for material map, normalMap, or alphaMap slots. load() returns the texture immediately and fills it later, while loadAsync() resolves a promise once decoding finishes. Set colorSpace to SRGBColorSpace for color maps and RepeatWrapping for tiled surfaces.
new THREE.TextureLoader ( manager )
Key points
- load(url, onLoad, onProgress, onError) returns the Texture before the image arrives.
- setCrossOrigin() defaults to 'anonymous' and must match your image host's CORS policy.
- Configure repeat, anisotropy, and filters on the returned texture, not on the loader.
Example
const loader = new THREE.TextureLoader();
loader.setCrossOrigin('anonymous');
const colorMap = loader.load(
'/textures/facade.jpg',
function (texture) {
texture.colorSpace = THREE.SRGBColorSpace;
texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
console.log('贴图就绪', texture.image.width, texture.image.height);
},
undefined,
function (error) {
console.error('贴图加载失败', error);
}
);
const material = new THREE.MeshStandardMaterial({
map: colorMap,
roughness: 0.7
});
const normalMap = await loader.loadAsync('/textures/facade-normal.jpg');
normalMap.wrapS = normalMap.wrapT = THREE.RepeatWrapping;
normalMap.repeat.set(4, 4);
Notes
- Assuming the image is ready right after load() leads to blank materials on first frame.
- Power-of-two texture sizes are required for reliable repeat and mipmaps on older devices.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). TextureLoader. https://www.jingweizhi.com/en/three/api/texture-loader.html (accessed 2026-11-03).