EventDispatcher →

App

App class allows you to set up your 3D application more easily. It includes code to init WebGL renderer, load glTF scenes, auto-start animations as well as logic for basic camera controls.

Example


    // loaded GLTF 2.0 asset
    const url = 'template.gltf';

    // construct a new application with simple rotating preloader
    const app = new v3d.App('v3d-container', null, new v3d.SimplePreloader({ container: 'v3d-container' }));

    // load main scene
    app.loadScene(url, function() {
        app.enableControls();
        app.run();
        runCode();
    });

    function runCode() {
        // place your own code here
    }

Constructor

App(container, ctxSettings, preloader)

container - the id of an HTML-element or the HTML-element itself to contain the canvas.
ctxSettings - the WebGL context attributes to be passed in the canvas.getContext() method.
preloader - the instance of application's Preloader class.

This constructor does the following:

Creates a new container element (if necessary).
Checks whether WebGL technology is supported, if not displays an error dialog.
Initializes an application clock.
Creates a new 3D canvas with WebGL 1.0 or WebGL 2.0 context and adds it to the container element.
Initializes a GLTF loader.
Prepares texture compression module.
Initializes methods for accelerated raycasting (BVH).
Adds an app instance to v3d.apps list (in case of non-modularized engine).

Properties

# .actions : Array

Array of animation actions used to schedule app animations. Instead of accessing this list directly you can also use the getAnimationActionByName method to search for an action by its clip name.

# .clearBkgOnLoad : Boolean

Set the scene background to null after loading a glTF scene. Default is false.

# .container : HTMLElement

A container element. This is a parent element for 3D Canvas used for rendering operations.

# .scene : Scene

Application main scene.

# .camera : Camera

Application main camera.

# .clock : Clock

Application clock object.

# .compileCallbacks : Array

Array of functions which will be called just before shader compilation. Shader compilation occurs during scene loading right after all assets (glTF metadata, binary, textures) has been fetched.

Use compile callback to enable post-processing or add fog, since adding these effects in runtime can negatively affect performance.



    function initFog(appInstance) {
        appInstance.scene.fog = new v3d.FogExp2('green', 0.01);
    }

    // loaded GLTF 2.0 asset
    const url = 'my_scene.gltf';

    // construct a new application with simple rotating preloader
    const app = new v3d.App('v3d-container', null, new v3d.SimplePreloader({ container: 'v3d-container' }));

    // initialize fog just before shader compilation
    app.compileCallbacks.push(initFog);

    // load main scene
    app.loadScene(url, function() {
        app.enableControls();
        app.run();
    });

# .controls : null

Application main camera controls object.

# .frame : Number

Current rendering frame of the application.

# .frameRateDivider : Number

Application FPS divider. Use setFrameDivider to set this value.

# .mixer : AnimationMixer

Mixer used to play animations loaded from glTF data.

# .preloader : HTMLElement

App preloader element (exists only during scene loading)

# .renderer : WebGLRenderer

Application WebGL renderer.

# .renderCallbacks : Array

Array of functions which will be called every time when rendering begins.

# .loader : GLTFLoader

Application glTF loader.

# .worldCubemapRes : Number

Resolution of the cubemap texture representing the world material. Default is 1024.

# .xrControllers : Array

Array of controller objects for the active WebXR session.

# .xrSession : XRSession

Active WebXR session.

Methods

# .animate () : null

Handler for scene updates: rendering, animations and camera controls. Do not change unless you know what you are doing.

# .appendScene (url, loadCb, progressCb, errorCb, loadCameras, loadLights) : null

Append the scene from the specified glTF file to the current scene. The loadCb callback will receive the loaded scene as a parameter after the loading is finished.

If there is no active scene in the application, then nothing will be appended.

Such parameters as loadCameras and loadLights are used to specify if cameras and lights will be appended from the loaded scene. Both parameters are true by default.

# .disablePostprocessing (keepOutline) : null

Disable all post-processing effects (except outline when keepOutline=true).

# .disableRendering (after) : null

Disable graphics updates in the animation loop after the given amount of frames (specify 0 to disable immediately). The controls and the animation mixer will keep being updated and the render callbacks will keep being called.

# .disableSSAA () : null

Disable supersample anti-aliasing.

# .dispose () : null

Unloads the scene (by calling unload) and disposes the whole application, which includes cleaning up the application's renderer and removing the canvas element from the DOM. Emits the dispose event.

The application is no longer usable after disposing. This approach is best suited for cases where the complete clean up is needed.

# .enableControls () : null

Enable controls for the main app camera. Depending on the control type specified for the camera this method will give you 'ORBIT', 'FLYING' or static camera.

# .enablePostprocessing (effects) : null

Enable the given post-processing effects.

# .enableRendering () : null

Enable graphics updates in the animation loop.

# .enableSSAA (sampleLevel, iterative) : null

Enable supersample anti-aliasing. The number of samples is calculated as 2^sampleLevel (e.g specify 4 to enable 16x SSAA).

# .getCamera () : Camera

Returns the main app camera.

# .getHeight () : number

Return calculated container element height.

# .getWidth () : number

Return calculated container element width.

# .hideFPS () : null

Hide frame rate counter.

# .initPostprocessing () : null

Handler for app post-processing initialization. Do not change unless you know what you are doing.

# .initWebXR (mode, referenceSpaceType, successCb, failureCb, exitCb, options) : null

Initialize AR/VR session.

mode — "immersive-vr" for VR session, "immersive-ar" for AR session.
referenceSpaceType — one of "viewer", "local", "local-floor", "bounded-floor", "unbounded".
successCb — callback executed on success.
failureCb — callback executed when the method fails.
exitCb — callback executed when the user leaves WebXR session.
options — dictionary object with additional params, such as domOverlay to enable HTML in AR mode.

# .loadScene (url, loadCb, progressCb, errorCb) : null

Load the glTF scene. The loadCb callback will receive the loaded scene as a parameter after the loading is finished. Emits the sceneLoad event.

If there already is an active scene (e.g. loaded before via the loadScene method), then use unload first to avoid conflicts between the existed scene and the loaded one.

# .onResize () : null

Handler for canvas resize event. Do not change unless you know what you are doing.

# .pause () : null

Pauses the application: animation, controls, render callbacks and rendering. Emits the pause event.

# .printPerformanceInfo (delta) : null

Estimate and print out rendering performance profile. delta is an optional period of estimation (default 1).

# .render () : null

Handler for scene rendering. Do not change unless you know what you are doing. Emits the beforeRender and afterRender events.

# .resume () : null

Resumes the application: animation, controls, render callbacks and rendering. Emits the resume event.

# .run () : null

Starts the application by removing the preloader and starting the rendering cycle.

# .setCamera (camera) : Camera

Set the main app camera.

# .setFrameRateDivider (divider : Integer) : null

Lowers the maximum frame by dividing it by a specified integer number. By default the engine tries to render scenes at 60 frames per second. If the divider is set to 2, for example, the FPS will be topped out to 30.

# .showFPS () : null

Show frame rate counter.

# .unload (rootObj) : null

rootObj -- (optional) an object to unload along with its children; if no object is given or the given object is the main application scene then the method performs full scene cleanup.

Unloads either a part or the whole scene depending on the parameters.

If the given rootObj is one of the scene objects, then this method removes the given object and its descendants from the scene and also frees the related resources (geometries, materials, textures, etc...). If the given rootObj is the scene instance itself, then this method performs full scene cleanup, which includes disposing all objects, the scene's environment, cameras and camera controls, animations, postprocessing, internal webgl objects, etc...

After the application's scene was fully unloaded the loadScene method can be used to load a completely new scene. This approach is best suited for loading/unloading multiple scenes without disposing the whole application.

# .updateEnvironment (wMat) : null

Update world environment from the specified material. Such material is usually stored in the Scene.worldMaterial property.

# .updateEnvMapProbes (object3d) : null

object3d - an object or a scene for searching probe objects among its descendants

Update all CubeReflectionProbe objects that are descendants of the given object3d object.

Events

#afterFirstRender

An event emitted right after the first frame rendered. You can subscribe to it as follows: app.addEventListener('afterFirstRender', e => ...); // properties of e: type ('afterFirstRender'), target (instance of App)

#afterRender

An event emitted after each frame rendered (in the beginning of the render method). You can subscribe to it as follows: app.addEventListener('afterRender', e => ...); // properties of e: type ('afterRender'), target (instance of App)

#beforeRender

An event emitted before each frame rendered (in the end of the render method). You can subscribe to it as follows: app.addEventListener('beforeRender', e => ...); // properties of e: type ('beforeRender'), target (instance of App)

#dispose

An event emitted right after the application is disposed via the dispose method. You can subscribe to it as follows: app.addEventListener('dispose', e => ...); // properties of e: type ('dispose'), target (instance of App)

#pause

An event emitted when the application is paused via the pause method. You can subscribe to it as follows: app.addEventListener('pause', e => ...); // properties of e: type ('pause'), target (instance of App)

#resume

An event emitted when the application is resumed via the resume method. You can subscribe to it as follows: app.addEventListener('resume', e => ...); // properties of e: type ('resume'), target (instance of App)

#sceneLoad

An event emitted after the app's scene is done loading, parsing and all its shaders are compiled. This event is emitted as a result of calling the loadScene method. You can subscribe to it as follows: app.addEventListener('sceneLoad', e => ...); // properties of e: type ('sceneLoad'), target (instance of App)

Source

For more info on how to obtain the source code of this module see this page.