Three.js Tutorial

Three.js Tutorial Three.js Installation Compatibility and Running Locally Three.js Lines and Texts Three.js Loading 3D Models Three.js Updating Things Three.js Disposing of an Object Three.js Creating VR Content Three.js Using post-processing Three.js Matrix Transformations Three.js Animation Systems Three.js Testing with NPM Three.js AnimationAction Three.js AnimationClip Three.js AnimationMixer Animation Object Group and Utils Three.js Keyframe Track Property Binding and Mixer Three.js Animation/ Tracks Three.js Audio Three.js Camera Three.js Buffer Attribute Three.js Buffer Geometry Three.js Interleaved Buffer Three.js Layers Three.js Object3D Three.js Raycaster Three.js Uniform Three.js Curves Three.js Geometries- 1 Three.js Helpers- 1 Three.js Helpers- 2 Three.js Lights Three.js Shadows Three.js Loaders- 1 Three.js Loaders- 2 Three.js Managers Three.js Materials Three.js Materials- Mesh Three.js Materials- 3 Three.js Math Three.js Interpolant Three.js Objects Three.js Renderers Three.js Scenes

ThreeJS Loaders 2
2022-04-27 09:49:26

ThreeJS Loaders 2

ImageBitmapLoader

A loader that converts an image to an ImageBitmap. An ImageBitmap provides an asynchronous and resource-efficient path for preparing textures for WebGL rendering.

ImageBitmapLoader, unlike FileLoader, does not prevent multiple concurrent requests to the same URL.

Texture.flipY and Texture.premultiplyAlpha with ImageBitmap are not supported. ImageBitmap requires these settings during bitmap creation, whereas regular images require them during GPU uploading. The equivalent options must be set via ImageBitmapLoader. instead, use setOptions.

Code Example

// instantiate a loader
const loader = new THREE.ImageBitmapLoader();
// set options if needed
loader.setOptions( { imageOrientation: 'flipY' } );
// load a image resource
loader.load(
          // resource URL
          'textures/skyboxsun25degtest.png',
          // onLoad callback
          function ( imageBitmap ) {
                   const texture = new THREE.CanvasTexture( imageBitmap );
                   const material = new THREE.MeshBasicMaterial( { map: texture } );
          },
          // onProgress callback currently not supported
          undefined,
          // onError callback
          function ( err ) {
                   console.log( 'An error happened' );
          }
);

Constructor

ImageBitmapLoader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new ImageBitmapLoader.

Properties

See the base Loader class for common properties.

.options : String

An optional object that sets options for the internally used createImageBitmap factory method. Default is undefined.

Methods

See the base Loader class for common methods.

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : undefined

url — the path or URL to the file. This can also be a Data URI.

onLoad — Will be called when load completes. The argument will be the loaded image.

onProgress (optional) — This callback function is currently not supported.

onError (optional) — Will be called when load errors.

Begin loading from url and return the image object that will contain the data.

.setOptions ( options : Object ) : this

Sets the options object for createImageBitmap.

ImageLoader

A loader for loading an Image. This is used internally by the CubeTextureLoader, ObjectLoader and TextureLoader.

Code Example

// instantiate a loader
const loader = new THREE.ImageLoader();
// load a image resource
loader.load(
          // resource URL
          'textures/skyboxsun25degtest.png',
                    
          // onLoad callback
          function ( image ) {
                   // use the image, e.g. draw part of it on a canvas
                   const canvas = document.createElement( 'canvas' );
                   const context = canvas.getContext( '2d' );
                   context.drawImage( image, 100, 100 );
          },
          // onProgress callback currently not supported
          undefined,
          // onError callback
          function () {
                   console.error( 'An error happened.' );
          }
);

Please note three.js r84 dropped support for ImageLoader progress events. For an ImageLoader that supports progress events, see this thread.

Examples

WebGL / loader / obj

WebGL / shaders / ocean

Constructor

ImageLoader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new ImageLoader.

Properties

See the base Loader class for common properties.

Methods

See the base Loader class for common methods.

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : HTMLImageElement

url — the path or URL to the file. This can also be a Data URI.

onLoad — Will be called when load completes. The argument will be the loaded image.

onProgress (optional) — This callback function is currently not supported.

onError (optional) — Will be called when load errors.

Begin loading from url and return the image object that will contain the data.

Loader

Base class for implementing loaders.

Constructor

Loader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new Loader.

Properties

.crossOrigin : String

The crossOrigin string to implement CORS for loading the url from a different domain that allows CORS. Default is anonymous.

.withCredentials : Boolean

Whether the XMLHttpRequest uses credentials. See .setWithCredentials. Default is false.

.manager : LoadingManager

The loadingManager the loader is using. Default is DefaultLoadingManager.

.path : String

The base path from which the asset will be loaded. Default is the empty string.

.resourcePath : String

The base path from which additional resources like textures will be loaded. Default is the empty string.

.requestHeader : Object

The request header used in HTTP request. See .setRequestHeader. Default is empty object.

Methods

.load () : undefined

This method needs to be implement by all concrete loaders. It holds the logic for loading the asset from the backend.

.loadAsync ( url : String, onProgress : Function ) : Promise

url — A string containing the path/URL of the file to be loaded.

onProgress (optional) — A function to be called while the loading is in progress. The argument will be the ProgressEvent instance, which contains .lengthComputable, .total and .loaded. If the server does not set the Content-Length header; .total will be 0.

This method is equivalent to .load, but returns a Promise.

onLoad is handled by Promise.resolve and onError is handled by Promise.reject.

.parse () : undefined

This method needs to be implement by all concrete loaders. It holds the logic for parsing the asset into three.js entities.

.setCrossOrigin ( crossOrigin : String ) : this

crossOrigin — The crossOrigin string to implement CORS for loading the url from a different domain that allows CORS.

.setWithCredentials ( value : Boolean ) : this

Whether the XMLHttpRequest uses credentials such as cookies, authorization headers or TLS client certificates. See XMLHttpRequest.withCredentials.

Note that this has no effect if you are loading files locally or from the same domain.

.setPath ( path : String ) : this

path — Set the base path for the asset.

.setResourcePath ( resourcePath : String ) : this

resourcePath — Set the base path for dependent resources like textures.

.setRequestHeader ( requestHeader : Object ) : this

requestHeader - key: The name of the header whose value is to be set. value: The value to set as the body of the header.

Set the request header used in HTTP request.

LoaderUtils

An object with several loader utility functions.

Functions

.decodeText ( array : TypedArray ) : String

array — A stream of bytes as a typed array.

The function takes a stream of bytes as input and returns a string representation.

.extractUrlBase ( url : String ) : String

url — The url to extract the base url from.

Extract the base from the URL.

.resolveURL ( url : String, path : String ) : String

url — The absolute or relative url resolve. path — The base path for relative urls to be resolved against.

Resolves relative urls against the given path. Absolute paths, data urls, and blob urls will be returned as is. Invalid urls will return an empty string.

MaterialLoader

A loader for loading a Material in JSON format. This uses the FileLoader internally for loading files.

Code Example

// instantiate a loader
const loader = new THREE.MaterialLoader();
// load a resource
loader.load(
          // resource URL
          'path/to/material.json',
          // onLoad callback
          function ( material ) {
                    object.material = material;
          },
          // onProgress callback
          function ( xhr ) {
                   console.log( (xhr.loaded / xhr.total * 100) + '% loaded' );
          },
          // onError callback
          function ( err ) {
                   console.log( 'An error happened' );
          }
);

Constructor

MaterialLoader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new MaterialLoader.

Properties

See the base Loader class for common properties.

.textures : Object

Object holding any textures used by the material. See .setTextures.

Methods

See the base Loader class for common methods.

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : undefined

url — the path or URL to the file. This can also be a Data URI.

onLoad — Will be called when load completes. The argument will be the loaded Material.

onProgress (optional) — Will be called while load progresses. The argument will be the ProgressEvent instance, which contains .lengthComputable, .total and .loaded. If the server does not set the Content-Length header; .total will be 0.

onError (optional) — Will be called when load errors.

Begin loading from url.

.parse ( json : Object ) : Material

json — The json object containing the parameters of the Material.

Parse a JSON structure and create a new Material of the type json.type with parameters defined in the json object.

.setTextures ( textures : Object ) : this

textures — object containing any textures used by the material.

ObjectLoader

A loader for loading a JSON resource in the JSON Object/Scene format.

This uses the FileLoader internally for loading files.

Code Example

const loader = new THREE.ObjectLoader();
loader.load(
          // resource URL
          "models/json/example.json",
          // onLoad callback
          // Here the loaded data is assumed to be an object
          function ( obj ) {
                   // Add the loaded object to the scene
                   scene.add( obj );
          },
          // onProgress callback
          function ( xhr ) {
                   console.log( (xhr.loaded / xhr.total * 100) + '% loaded' );
          },
          // onError callback
          function ( err ) {
                   console.error( 'An error happened' );
          }
);
// Alternatively, to parse a previously loaded JSON structure
const object = loader.parse( a_json_object );
scene.add( object );

Constructor

ObjectLoader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new ObjectLoader.

Properties

See the base Loader class for common properties.

Methods

See the base Loader class for common methods.

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : undefined

url — the path or URL to the file. This can also be a Data URI.

onLoad — Will be called when load completes. The argument will be the loaded object.

onProgress (optional) — Will be called while load progresses. The argument will be the ProgressEvent instance, which contains .lengthComputable, .total and .loaded. If the server does not set the Content-Length header; .total will be 0.

onError (optional) — Will be called when load errors.

Begin loading from url and call onLoad with the parsed response content.

.parse ( json : Object, onLoad : Function ) : Object3D

json — required. The JSON source to parse.

onLoad — Will be called when parsed completes. The argument will be the parsed object.

Parse a JSON structure and return a threejs object. This is used internally by .load() but can also be used directly to parse a previously loaded JSON structure.

.parseGeometries ( json : Object ) : Object

json — required. The JSON source to parse.

This is used by .parse() to parse any geometries in the JSON structure.

.parseMaterials ( json : Object ) : Object

json — required. The JSON source to parse.

This is used by .parse() to parse any materials in the JSON structure using MaterialLoader.

.parseAnimations ( json : Object ) : Object

json — required. The JSON source to parse.

This is used by .parse() to parse any animations in the JSON structure, using AnimationClip.parse().

.parseImages ( json : Object ) : Object

json — required. The JSON source to parse.

This is used by .parse() to parse any images in the JSON structure, using ImageLoader.

.parseTextures ( json : Object ) : Object

json — required. The JSON source to parse.

This is used by .parse() to parse any textures in the JSON structure.

.parseObject ( json : Object, geometries : BufferGeometry, materials : Material, animations : AnimationClip ) : Object3D

json — required. The JSON source to parse.

geometries — required. The geometries of the JSON.

materials — required. The materials of the JSON.

animations — required. The animations of the JSON.

This is used by .parse() to parse any 3D objects in the JSON structure.

TextureLoader

Class for loading a texture. This uses the ImageLoader internally for loading files.

Code Example

const texture = new THREE.TextureLoader().load( 'textures/land_ocean_ice_cloud_2048.jpg' );
// immediately use the texture for material creation
const material = new THREE.MeshBasicMaterial( { map: texture } );

Code Example with Callbacks

// instantiate a loader
const loader = new THREE.TextureLoader();
// load a resource
loader.load(
          // resource URL
          'textures/land_ocean_ice_cloud_2048.jpg',
          // onLoad callback
          function ( texture ) {
                   // in this example we create the material when the texture is loaded
                   const material = new THREE.MeshBasicMaterial( {
                             map: texture
                    } );
          },
          // onProgress callback currently not supported
          undefined,
          // onError callback
          function ( err ) {
                   console.error( 'An error happened.' );
          }
);

Please note three.js r84 dropped support for TextureLoader progress events. For a TextureLoader that supports progress events, see this thread.

Examples

geometry / cube

Constructor

TextureLoader( manager : LoadingManager )

manager — The loadingManager for the loader to use. Default is THREE.DefaultLoadingManager.

Creates a new TextureLoader.

Properties

See the base Loader class for common properties.

Methods

See the base Loader class for common methods.

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : Texture

url — the path or URL to the file. This can also be a Data URI.

onLoad (optional) — Will be called when load completes. The argument will be the loaded texture.

onProgress (optional) — This callback function is currently not supported.

onError (optional) — Will be called when load errors.

Begin loading from the given URL and pass the fully loaded texture to onLoad. The method also returns a new texture object which can directly be used for material creation. If you do it this way, the texture may pop up in your scene once the respective loading process is finished.