texture-generator

Procedural Equirectangular Textures

generator.js

Module. Implements the equirectangular texture generator and provides the result as a texture. The pattern of the texture is computed by a user-defined callback function.

• API Reference
    texture
    [ ].update
    [ ].border
• Generation customization
    Pattern functions
    Pattern options
    Deferred generation

texture(…)

Function. Generates an equirectangular texture. Mipmaps are turned off. Parameters of texture can be passed in any order.

texture( pattern, {options}, {canvas}, {deferred} )

where:

• pattern – user-defined callback pattern function that computes the texture
• options – optional object with pattern-specific internal options
• canvas – optional HTML canvas for rendering; if not provided, a new canvas is created
• deferred – optional boolean whether the texture generation is deferred

The function returns a THREE.CanvasTexture object enriched by instance methods: update and border.

[texture].update(…)

Instance method. Added to any texture created by texture. Updates a deferred texture by calculating as much as it is possible, within a set time constraint. While the texture is not complete, update generates at least one row of texture pixels per call.

myTexture.update( {ms} )

where:

• ms – suggested time in miliseconds to spend on generation of textures rows, by default ms is 20

This instance method returns a number ∈ [0,1] for how much of the texture generated, i.e. 0.5 means 50%, 1 means 100%. This includes the newly generated rows. If the texture is completely generated, no new rows are calculated and the return value is immediately 1.

[texture].border(…)

Instance method. Added to any texture created by texture. Draws rows of red pixels in the yet to be generated part of the texture.

myTexture.border( {rows} )

where:

• rows – suggested number of rows, by default rows is 1

Pattern function

Callback function. A pattern function is a user-defind function that generates a specific pattern. The function calculates the color of a point in 3D space, based on its (x,y,z) coordinates, its texture coordinates (u,v) and its pixel coordinates (px,py).

pattern( x,y,z, color )
pattern( x,y,z, color, options )
pattern( x,y,z, color, options, u,v )
pattern( x,y,z, color, options, u,v, px,py )

where:

• x,y,z – coordiates of a point on a sphere, x,y,z ∈ [-1,1].
• color – THREE.Color; its properties r,g,b ∈ [0,1] must be updated by the pattern function. An additional color property a ∈ [0,1] could be set for encoding alpha transparency.
• options – object; contains customization parameters of the pattern function.
• u,v – optional texture coordiates of a pixel on the texture, u,v ∈ [0,1].
• px,py – optional integer coordiates of a pixel in the texture, px ∈ [0,width-1], py ∈ [0,height-1].

The width and height of the texture can be retrieved from parameters options.width and options.height.

Pattern options

The generation of each texture may require additional parameters. They are provided as a JS object, passed to texture as options parameter. The properties of the options are:

• .$name – texture name (text, optional)
• .width – texture width in pixels (integer, optional)
• .height – texture height in pixels (integer, optional)
• … – other pattern-specific options

If width and height are not provided, the texture size is taken from the canvas size. If the canvas is also not provided, the default size 1024×512 pixels is used.

All properties starting with $ character are not used by the texture generator, but could be useful for software that incorporates the generator.

Example:

{
	width: 1024,
	height: 512,
	color: 0xFF80D0,
	scale: 5.1
}

Deferred generation

By default a texture is generated as a single step. For large or complex textures this blocks the user interface. Deferred generation prevents blocking by distributing calculations in small steps. Calculations are initialized by texture’s instance method [ ].update.

Deferred generation sets .needsUpdate only when the texture is complete.

A typical implementation of deferred generation that spends 10 ms during each frame and continuously updates the texture on the screen, may look like this:

map = texture( pattern, true, options );
	
function animationLoop( )
{
	if( map.update(10) < 1 )
		map.needsUpdate = true;
	...
	renderer.render( scene, camera );
}

Source

src/generator.js

Back

This site is open source. Improve this page.