App3D

clay.application. App3D

# new App3D(dom, appNS)

Source:

Using App3D is a much more convenient way to create and manage your 3D application.

It provides the abilities to:

  • Manage application loop and rendering.
  • Collect GPU resource automatically without memory leak concern.
  • Mouse event management.
  • Create scene objects, materials, textures with simpler code.
  • Load models with one line of code.
  • Promised interfaces.

Here is a basic example to create a rotating cube.

var app = clay.application.create('#viewport', {
    init: function (app) {
        // Create a perspective camera.
        // First parameter is the camera position. Which is in front of the cube.
        // Second parameter is the camera lookAt target. Which is the origin of the world, and where the cube puts.
        this._camera = app.createCamera([0, 2, 5], [0, 0, 0]);
        // Create a sample cube
        this._cube = app.createCube();
        // Create a directional light. The direction is from top right to left bottom, away from camera.
        this._mainLight = app.createDirectionalLight([-1, -1, -1]);
    },
    loop: function (app) {
        // Simply rotating the cube every frame.
        this._cube.rotation.rotateY(app.frameTime / 1000);
    }
});
Parameters:
Name Type Description
dom DomQuery

Container dom element or a selector string that can be used in querySelector
appNS App3DNamespace

Options and namespace used in creating app3D

Members

# container :HTMLElement

Source:

Container dom element

Type:
  • HTMLElement

# elapsedTime :number

Source:

Time elapsed since application created.

Type:
  • number

# frameTime :number

Source:

Time elapsed since last frame. Can be used in loop to calculate the movement.

Type:
  • number

# height :number

Source:

Height of viewport.

Type:
  • number

# methods :number

Source:

Methods from clay.application.create

Type:
  • number

# renderer :clay.Renderer

Source:
Type:

# scene :clay.Renderer

Source:
Type:

# timeline :clay.Renderer

Source:
Type:

# width :number

Source:

Width of viewport.

Type:
  • number

Methods

# cloneNode(node, parentNodeopt) → {clay.Node}

Source:

Similar to app.scene.cloneNode, except it will mount the cloned node to the scene automatically. See more in clay.Scene#cloneNode

Parameters:
Name Type Attributes Description
node clay.Node
parentNode clay.Node <optional>

Parent node that new cloned node will be mounted. Default to have same parent with source node.
Returns:
Type
clay.Node

# createAmbientCubemapLight(envImageopt, specularIntenstityopt, diffuseIntenstityopt, exposureopt, prefilteredCubemapSizeopt) → {Promise}

Source:

Create an cubemap ambient light and an spherical harmonic ambient light for specular and diffuse lighting in PBR rendering

Parameters:
Name Type Attributes Default Description
envImage ImageLike | TextureCube <optional>

Panorama environment image, HDR format is better. Or a pre loaded texture cube
specularIntenstity number <optional>
 0.7

Intensity of specular light.
diffuseIntenstity number <optional>
 0.7

Intensity of diffuse light.
exposure number <optional>
 1

Exposure of HDR image. Only if image in first paramter is HDR.
prefilteredCubemapSize number <optional>
 32

The size of prefilerted cubemap. Larger value will take more time to do expensive prefiltering.
Returns:
Type
Promise

# createAmbientLight(coloropt, intensityopt)

Source:

Create a ambient light.

Parameters:
Name Type Attributes Default Description
color Color <optional>
 '#fff'

Color of ambient light.
intensity number <optional>
 1

Intensity of ambient light.

# createCamera(position, target, typeopt, extentopt) → {clay.camera.Perspective|clay.camera.Orthographic}

Source:

Create a perspective or orthographic camera and add it to the scene.

Parameters:
Name Type Attributes Default Description
position Array.<number> | clay.Vector3
target Array.<number> | clay.Vector3
type string <optional>
 "perspective"

Can be 'perspective' or 'orthographic'(in short 'ortho')
extent Array.<number> | clay.Vector3 <optional>

Extent is available only if type is orthographic.
Returns:
Type
clay.camera.Perspective | clay.camera.Orthographic

# createCube(materialopt, parentNodeopt, subdivisionopt) → {clay.Mesh}

Source:

Create a cube mesh and add it to the scene or the given parent node.

Example
// Create a white cube.
 app.createCube()
Parameters:
Name Type Attributes Default Description
material Object | clay.Material <optional>
parentNode clay.Node <optional>

Parent node to append. Default to be scene.
subdivision Array.<number> | number <optional>
 1

Subdivision of cube. Can be a number to represent both width, height and depth dimensions. Or an array to represent them respectively.
Returns:
Type
clay.Mesh

# createCubeInside(materialopt, parentNodeopt, subdivisionopt) → {clay.Mesh}

Source:

Create a cube mesh that camera is inside the cube.

Example
// Create a white cube inside.
 app.createCubeInside()
Parameters:
Name Type Attributes Default Description
material Object | clay.Material <optional>
parentNode clay.Node <optional>

Parent node to append. Default to be scene.
subdivision Array.<number> | number <optional>
 1

Subdivision of cube. Can be a number to represent both width, height and depth dimensions. Or an array to represent them respectively.
Returns:
Type
clay.Mesh

# createDirectionalLight(dir, coloropt, intensityopt)

Source:

Create a directional light and add it to the scene.

Example
app.createDirectionalLight([-1, -1, -1], '#fff', 2);
Parameters:
Name Type Attributes Default Description
dir Array.<number> | clay.Vector3

A Vector3 or array to represent the direction.
color Color <optional>
 '#fff'

Color of directional light, default to be white.
intensity number <optional>

Intensity of directional light, default to be 1.

# createMaterial(shaderopt, transparentopt, textureConvertToPOTopt, textureFlipYopt, textureLoadedopt, texturesReadyopt) → {clay.Material}

Source:

Create a material.

Parameters:
Name Type Attributes Default Description
materialConfig. Object | StandardMaterialMRConfig

materialConfig contains shader, transparent and uniforms that used in corresponding uniforms. Uniforms can be color, alpha diffuseMap etc.
shader string | clay.Shader <optional>
 'clay.standardMR'

Default to be standard shader with metalness and roughness workflow.
transparent boolean <optional>
 false

If material is transparent.
textureConvertToPOT boolean <optional>
 false

Force convert None Power of Two texture to Power of two so it can be tiled.
textureFlipY boolean <optional>
 true

If flip y of texture.
textureLoaded function <optional>

Callback when single texture loaded.
texturesReady function <optional>

Callback when all texture loaded.
Returns:
Type
clay.Material

# createMesh(geometry) → {clay.Mesh}

Source:

Create a general mesh with given geometry instance and material config.

Parameters:
Name Type Description
geometry clay.Geometry
Returns:
Type
clay.Mesh

# createNode(parentNode) → {clay.Node}

Source:

Create an empty node

Parameters:
Name Type Description
parentNode clay.Node
Returns:
Type
clay.Node

# createParametricSurface(materialopt, parentNodeopt, generator) → {clay.Mesh}

Source:

Create mesh with parametric surface function

Parameters:
Name Type Attributes Description
material Object | clay.Material <optional>
parentNode clay.Node <optional>

Parent node to append. Default to be scene.
generator Object
Properties
Name Type Attributes Default Description
x function
y function
z function
u Array <optional>
 [0, 1, 0.05]
v Array <optional>
 [0, 1, 0.05]
Returns:
Type
clay.Mesh

# createPlane(materialopt, parentNodeopt, subdivisionopt) → {clay.Mesh}

Source:

Create a plane mesh and add it to the scene or the given parent node.

Example
// Create a red color plane.
 app.createPlane({
     color: [1, 0, 0]
 })
Parameters:
Name Type Attributes Default Description
material Object | clay.Material <optional>
parentNode clay.Node <optional>

Parent node to append. Default to be scene.
subdivision Array.<number> | number <optional>
 1

Subdivision of plane. Can be a number to represent both width and height dimensions. Or an array to represent them respectively.
Returns:
Type
clay.Mesh

# createPointLight(position, rangeopt, coloropt, intensityopt)

Source:

Create a point light.

Parameters:
Name Type Attributes Default Description
position Array.<number> | clay.Vector3

Position of point light..
range number <optional>
 100

Falloff range of point light.
color Color <optional>
 '#fff'

Color of point light.
intensity number <optional>
 1

Intensity of point light.

# createSphere(materialopt, parentNodeopt, subdivisionopt) → {clay.Mesh}

Source:

Create a sphere mesh and add it to the scene or the given parent node.

Example
// Create a semi-transparent sphere.
 app.createSphere({
     color: [0, 0, 1],
     transparent: true,
     alpha: 0.5
 })
Parameters:
Name Type Attributes Default Description
material Object | clay.Material <optional>
parentNode clay.Node <optional>

Parent node to append. Default to be scene.
subdivision number <optional>
 20

Subdivision of sphere.
Returns:
Type
clay.Mesh

# createSpotLight(position, targetopt, rangeopt, coloropt, intensityopt, umbraAngleopt, penumbraAngleopt)

Source:

Create a spot light and add it to the scene.

Example
app.createSpotLight([5, 5, 5], [0, 0, 0], 20, #900);
Parameters:
Name Type Attributes Default Description
position Array.<number> | clay.Vector3

Position of the spot light.
target Array.<number> | clay.Vector3 <optional>

Target position where spot light points to.
range number <optional>
 20

Falloff range of spot light. Default to be 20.
color Color <optional>
 '#fff'

Color of spot light, default to be white.
intensity number <optional>
 1

Intensity of spot light, default to be 1.
umbraAngle number <optional>
 30

Umbra angle of spot light. Default to be 30 degree from the middle line.
penumbraAngle number <optional>
 45

Penumbra angle of spot light. Default to be 45 degree from the middle line.

# dispose()

Source:

Dispose the application

# loadModel(url, opts, parentNodeopt) → {Promise}

Source:

Load a glTF format model. You can convert FBX/DAE/OBJ format models to glTF with fbx2gltf python script, or simply using the Clay Viewer client application.

Parameters:
Name Type Attributes Description
url string
opts Object
Properties
Name Type Attributes Default Description
shader string | clay.Shader <optional>
 'clay.standard'

'basic'|'lambert'|'standard'.
waitTextureLoaded boolean <optional>
 false

If add to scene util textures are all loaded.
autoPlayAnimation boolean <optional>
 true

If autoplay the animation of model.
upAxis boolean <optional>
 'y'

Change model to y up if upAxis is 'z'
textureFlipY boolean <optional>
 false
textureConvertToPOT boolean <optional>
 false

If convert texture to power-of-two
textureRootPath string <optional>

Root path of texture. Default to be relative with glTF file.
parentNode clay.Node <optional>

Parent node that model will be mounted. Default to be scene
Returns:
Type
Promise

# loadTexture(img, optsopt, useCacheopt) → {Promise}

Source:

Load a texture from image or string.

Example
app.loadTexture('diffuseMap.jpg')
     .then(function (texture) {
         material.set('diffuseMap', texture);
     });
Parameters:
Name Type Attributes Description
img ImageLike
opts Object <optional>

Texture options.

Properties
Name Type Attributes Default Description
flipY boolean <optional>
 true

If flipY. See clay.Texture.flipY
convertToPOT boolean <optional>
 false

Force convert None Power of Two texture to Power of two so it can be tiled.
anisotropic number <optional>

Anisotropic filtering. See clay.Texture.anisotropic
wrapS number <optional>
 clay.Texture.REPEAT

See clay.Texture.wrapS
wrapT number <optional>
 clay.Texture.REPEAT

See clay.Texture.wrapT
minFilter number <optional>
 clay.Texture.LINEAR_MIPMAP_LINEAR

See clay.Texture.minFilter
magFilter number <optional>
 clay.Texture.LINEAR

See clay.Texture.magFilter
exposure number <optional>

Only be used when source is a HDR image.
useCache boolean <optional>

If use cache.
Returns:
Type
Promise

# loadTextureCube(img, optsopt) → {Promise}

Source:

Create a texture from image or string synchronously. Texture can be use directly and don't have to wait for it's loaded.

Example
app.loadTextureCube({
     px: 'skybox/px.jpg', py: 'skybox/py.jpg', pz: 'skybox/pz.jpg',
     nx: 'skybox/nx.jpg', ny: 'skybox/ny.jpg', nz: 'skybox/nz.jpg'
 }).then(function (texture) {
     skybox.setEnvironmentMap(texture);
 })
Parameters:
Name Type Attributes Description
img ImageLike
opts Object <optional>

Texture options.

Properties
Name Type Attributes Default Description
flipY boolean <optional>
 false

If flipY. See clay.Texture.flipY
Returns:
Type
Promise

# loadTextureCubeSync(img, optsopt) → {clay.TextureCube}

Source:

Create a texture from image or string synchronously. Texture can be use directly and don't have to wait for it's loaded.

Example
var texture = app.loadTextureCubeSync({
     px: 'skybox/px.jpg', py: 'skybox/py.jpg', pz: 'skybox/pz.jpg',
     nx: 'skybox/nx.jpg', ny: 'skybox/ny.jpg', nz: 'skybox/nz.jpg'
 });
 skybox.setEnvironmentMap(texture);
Parameters:
Name Type Attributes Description
img ImageLike
opts Object <optional>

Texture options.

Properties
Name Type Attributes Default Description
flipY boolean <optional>
 false

If flipY. See clay.Texture.flipY
Returns:
Type
clay.TextureCube

# loadTextureSync(img, optsopt) → {clay.Texture2D}

Source:

Create a texture from image or string synchronously. Texture can be use directly and don't have to wait for it's loaded.

Example
var texture = app.loadTexture('diffuseMap.jpg', {
     anisotropic: 8,
     flipY: false
 });
 material.set('diffuseMap', texture);
Parameters:
Name Type Attributes Description
img ImageLike
opts Object <optional>

Texture options.

Properties
Name Type Attributes Default Description
flipY boolean <optional>
 true

If flipY. See clay.Texture.flipY
convertToPOT boolean <optional>
 false

Force convert None Power of Two texture to Power of two so it can be tiled.
anisotropic number <optional>

Anisotropic filtering. See clay.Texture.anisotropic
wrapS number <optional>
 clay.Texture.REPEAT

See clay.Texture.wrapS
wrapT number <optional>
 clay.Texture.REPEAT

See clay.Texture.wrapT
minFilter number <optional>
 clay.Texture.LINEAR_MIPMAP_LINEAR

See clay.Texture.minFilter
magFilter number <optional>
 clay.Texture.LINEAR

See clay.Texture.magFilter
exposure number <optional>

Only be used when source is a HDR image.
Returns:
Type
clay.Texture2D

# render()

Source:

Do render