API.md

Classes

GltfView

GltfView represents a view on a gltf, e.g. in a canvas

GltfState

GltfState containing a state for visualization in GltfView

ResourceLoader

ResourceLoader can be used to load resources for the GltfState that are then used to display the loaded data with GltfView

UserCamera

GltfView

GltfView represents a view on a gltf, e.g. in a canvas

Kind: global class

• GltfView
  • new GltfView(context)
  • .createState() ⇒ GltfState
  • .createResourceLoader([externalDracoLib], [externalKtxLib]) ⇒ ResourceLoader
  • .renderFrame(state, width, height)
  • .gatherStatistics(state) ⇒ Object

new GltfView(context)

GltfView representing one WebGl 2.0 context or in other words one 3D rendering of the Gltf. You can create multiple views for example when multiple canvases should be shown on the same webpage.

Param	Type	Description
context	*	WebGl 2.0 context. Get it from a canvas with canvas.getContext("webgl2")

gltfView.createState() ⇒ GltfState

createState constructs a new GltfState for the GltfView. The resources referenced in a gltf state can directly be stored as resources on the WebGL context of GltfView, therefore GltfStates cannot not be shared between GltfViews.

Kind: instance method of GltfView
Returns: GltfState - GltfState

gltfView.createResourceLoader([externalDracoLib], [externalKtxLib]) ⇒ ResourceLoader

createResourceLoader creates a resource loader with which glTFs and environments can be loaded for the view

Kind: instance method of GltfView
Returns: ResourceLoader - ResourceLoader

Param	Type	Description
[externalDracoLib]	Object	optional object of an external Draco library, e.g. from a CDN
[externalKtxLib]	Object	optional object of an external KTX library, e.g. from a CDN

gltfView.renderFrame(state, width, height)

renderFrame to the context's default frame buffer Call this function in the javascript animation update loop for continuous rendering to a canvas

Kind: instance method of GltfView

Param	Type	Description
state	*	GltfState that is be used for rendering
width	*	of the viewport
height	*	of the viewport

gltfView.gatherStatistics(state) ⇒ Object

gatherStatistics collects information about the GltfState such as the number of rendered meshes or triangles

Kind: instance method of GltfView
Returns: Object - an object containing statistics information

Param	Type	Description
state	*	GltfState about which the statistics should be collected

GltfState

GltfState containing a state for visualization in GltfView

Kind: global class

• GltfState
  • new GltfState(view)
  • instance
    • .gltf
    • .environment
    • .userCamera
    • .sceneIndex
    • .cameraIndex
    • .animationIndices
    • .animationTimer
    • .variant
    • .renderingParameters
      • .morphing
      • .skinning
      • .clearcoat
      • .sheen
      • .transmission
      • .clearColor
      • .exposure
      • .usePunctual
      • .useIBL
      • .renderEnvironmentMap
      • .blurEnvironmentMap
      • .toneMap
      • .debugOutput
      • .environmentRotation
  • static
    • .ToneMaps
      • .NONE
      • .ACES_FAST
      • .ACES
    • .DebugOutput
      • .NONE
      • .METALLIC
      • .ROUGHNESS
      • .NORMAL
      • .WORLDSPACENORMAL
      • .GEOMETRYNORMAL
      • .TANGENT
      • .BITANGENT
      • .BASECOLOR
      • .OCCLUSION
      • .EMISSIVE
      • .DIFFUSE
      • .SPECULAR
      • .CLEARCOAT
      • .SHEEN
      • .TRANSMISSION
      • .ALPHA
      • .F0

new GltfState(view)

GltfState represents all state that can be visualized in a view. You could have multiple GltfStates configured and switch between them on demand.

Param	Type	Description
view	*	GltfView to which this state belongs

gltfState.gltf

loaded gltf data @see ResourceLoader.loadGltf

Kind: instance property of GltfState

gltfState.environment

loaded environment data @see ResourceLoader.loadEnvironment

Kind: instance property of GltfState

gltfState.userCamera

user camera @see UserCamera, convenient camera controls

Kind: instance property of GltfState

gltfState.sceneIndex

gltf scene that is visible in the view

Kind: instance property of GltfState

gltfState.cameraIndex

index of the camera that is used to render the view. a value of 'undefined' enables the user camera

Kind: instance property of GltfState

gltfState.animationIndices

indices of active animations

Kind: instance property of GltfState

gltfState.animationTimer

animation timer allows to control the animation time

Kind: instance property of GltfState

gltfState.variant

KHR_materials_variants

Kind: instance property of GltfState

gltfState.renderingParameters

parameters used to configure the rendering

Kind: instance property of GltfState

• .renderingParameters
  • .morphing
  • .skinning
  • .clearcoat
  • .sheen
  • .transmission
  • .clearColor
  • .exposure
  • .usePunctual
  • .useIBL
  • .renderEnvironmentMap
  • .blurEnvironmentMap
  • .toneMap
  • .debugOutput
  • .environmentRotation

renderingParameters.morphing

morphing between vertices

Kind: static property of renderingParameters

renderingParameters.skinning

skin / skeleton

Kind: static property of renderingParameters

renderingParameters.clearcoat

KHR_materials_clearcoat

Kind: static property of renderingParameters

renderingParameters.sheen

KHR_materials_sheen

Kind: static property of renderingParameters

renderingParameters.transmission

KHR_materials_transmission

Kind: static property of renderingParameters

renderingParameters.clearColor

clear color expressed as list of ints in the range [0, 255]

Kind: static property of renderingParameters

renderingParameters.exposure

exposure factor

Kind: static property of renderingParameters

renderingParameters.usePunctual

KHR_lights_punctual

Kind: static property of renderingParameters

renderingParameters.useIBL

image based lighting

Kind: static property of renderingParameters

renderingParameters.renderEnvironmentMap

render the environment map in the background

Kind: static property of renderingParameters

renderingParameters.blurEnvironmentMap

apply blur to the background environment map

Kind: static property of renderingParameters

renderingParameters.toneMap

which tonemap to use, use ACES for a filmic effect

Kind: static property of renderingParameters

renderingParameters.debugOutput

render some debug output channes, such as for example the normals

Kind: static property of renderingParameters

renderingParameters.environmentRotation

By default the front face of the environment is +Z (90) Front faces: +X = 0 +Z = 90 -X = 180 -Z = 270

Kind: static property of renderingParameters

GltfState.ToneMaps

ToneMaps enum for the different tonemappings that are supported by gltf sample viewer

Kind: static property of GltfState

• .ToneMaps
  • .NONE
  • .ACES_FAST
  • .ACES

ToneMaps.NONE

don't apply tone mapping

Kind: static property of ToneMaps

ToneMaps.ACES_FAST

fast implementation of the ACES sRGB RRT+ODT

Kind: static property of ToneMaps

ToneMaps.ACES

more accurate implementation of the ACES sRGB RRT+ODT

Kind: static property of ToneMaps

GltfState.DebugOutput

DebugOutput enum for selecting debug output channels such as "NORMAL"

Kind: static property of GltfState

• .DebugOutput
  • .NONE
  • .METALLIC
  • .ROUGHNESS
  • .NORMAL
  • .WORLDSPACENORMAL
  • .GEOMETRYNORMAL
  • .TANGENT
  • .BITANGENT
  • .BASECOLOR
  • .OCCLUSION
  • .EMISSIVE
  • .DIFFUSE
  • .SPECULAR
  • .CLEARCOAT
  • .SHEEN
  • .TRANSMISSION
  • .ALPHA
  • .F0

DebugOutput.NONE

standard rendering - debug output is disabled

Kind: static property of DebugOutput

DebugOutput.METALLIC

output the metallic value from pbr metallic roughness

Kind: static property of DebugOutput

DebugOutput.ROUGHNESS

output the roughness value from pbr metallic roughness

Kind: static property of DebugOutput

DebugOutput.NORMAL

output the normal map value in TBN space

Kind: static property of DebugOutput

DebugOutput.WORLDSPACENORMAL

output the world space normals (i.e. with TBN applied)

Kind: static property of DebugOutput

DebugOutput.GEOMETRYNORMAL

output the normal from the TBN

Kind: static property of DebugOutput

DebugOutput.TANGENT

output the tangent from the TBN

Kind: static property of DebugOutput

DebugOutput.BITANGENT

output the bitangent from the TBN

Kind: static property of DebugOutput

DebugOutput.BASECOLOR

output the base color value

Kind: static property of DebugOutput

DebugOutput.OCCLUSION

output the occlusion value

Kind: static property of DebugOutput

DebugOutput.EMISSIVE

output the emissive value

Kind: static property of DebugOutput

DebugOutput.DIFFUSE

output diffuse lighting

Kind: static property of DebugOutput

DebugOutput.SPECULAR

output specular lighting

Kind: static property of DebugOutput

DebugOutput.CLEARCOAT

output clearcoat lighting

Kind: static property of DebugOutput

DebugOutput.SHEEN

output sheen lighting

Kind: static property of DebugOutput

DebugOutput.TRANSMISSION

output tranmission lighting

Kind: static property of DebugOutput

DebugOutput.ALPHA

output the alpha value

Kind: static property of DebugOutput

DebugOutput.F0

output computed F0

Kind: static property of DebugOutput

ResourceLoader

ResourceLoader can be used to load resources for the GltfState that are then used to display the loaded data with GltfView

Kind: global class

• ResourceLoader
  • new ResourceLoader(view)
  • .loadGltf(gltfFile, [externalFiles]) ⇒ Promise
  • .loadEnvironment(environmentFile, [lutFiles]) ⇒ Promise
  • .initKtxLib([externalKtxLib])
  • .initDracoLib([externalDracoLib])

new ResourceLoader(view)

ResourceLoader class that provides an interface to load resources into the view. Typically this is created with GltfView.createResourceLoader() You cannot share resource loaders between GltfViews as some of the resources are allocated directly on the WebGl2 Context

Param	Type	Description
view	Object	the GltfView for which the resources are loaded

resourceLoader.loadGltf(gltfFile, [externalFiles]) ⇒ Promise

loadGltf asynchroneously and create resources for rendering

Kind: instance method of ResourceLoader
Returns: Promise - a promise that fulfills when the gltf file was loaded

Param	Type	Description
gltfFile	String | ArrayBuffer | File	the .gltf or .glb file either as path or as preloaded resource. In node.js environments, only ArrayBuffer types are accepted.
[externalFiles]	Array.<File>	additional files containing resources that are referenced in the gltf

resourceLoader.loadEnvironment(environmentFile, [lutFiles]) ⇒ Promise

loadEnvironment asynchroneously, run IBL sampling and create resources for rendering

Kind: instance method of ResourceLoader
Returns: Promise - a promise that fulfills when the environment file was loaded

Param	Type	Description
environmentFile	String | ArrayBuffer | File	the .hdr file either as path or resource
[lutFiles]	Object	object containing paths or resources for the environment look up textures. Keys are lut_ggx_file, lut_charlie_file and lut_sheen_E_file

resourceLoader.initKtxLib([externalKtxLib])

initKtxLib must be called before loading gltf files with ktx2 assets

Kind: instance method of ResourceLoader

Param	Type	Description
[externalKtxLib]	Object	external ktx library (for example from a CDN)

resourceLoader.initDracoLib([externalDracoLib])

initDracoLib must be called before loading gltf files with draco meshes

Kind: instance method of ResourceLoader

Param	Type	Description
[externalDracoLib]	*	external draco library (for example from a CDN)

UserCamera

Kind: global class

• UserCamera
  • new UserCamera()
  • .setVerticalFoV(yfov)
  • .getPosition()
  • .getRotation()
  • .getLookDirection()
  • .getTarget()
  • .lookAt(from, to)
  • .setPosition(position)
  • .setTarget(target)
  • .setRotation(yaw, pitch)
  • .setDistanceFromTarget(distance, target)
  • .zoomBy(value)
  • .orbit(x, y)
  • .pan(x, y)
  • .fitViewToScene(gltf, sceneIndex)

new UserCamera()

Create a new user camera.

userCamera.setVerticalFoV(yfov)

Sets the vertical FoV of the user camera.

Kind: instance method of UserCamera

Param	Type
yfov	number

userCamera.getPosition()

Returns the current position of the user camera as a vec3.

Kind: instance method of UserCamera

userCamera.getRotation()

Returns the current rotation of the user camera as quat.

Kind: instance method of UserCamera

userCamera.getLookDirection()

Returns the normalized direction the user camera looks at as vec3.

Kind: instance method of UserCamera

userCamera.getTarget()

Returns the current target the camera looks at as vec3. This multiplies the viewing direction with the distance. For distance 0 the normalized viewing direction is used.

Kind: instance method of UserCamera

userCamera.lookAt(from, to)

Look from user camera to target. This changes the transformation of the user camera.

Kind: instance method of UserCamera

Param	Type
from	vec3
to	vec3

userCamera.setPosition(position)

Sets the position of the user camera.

Kind: instance method of UserCamera

Param	Type
position	vec3

userCamera.setTarget(target)

This rotates the user camera towards the target and sets the position of the user camera according to the current distance.

Kind: instance method of UserCamera

Param	Type
target	vec3

userCamera.setRotation(yaw, pitch)

Sets the rotation of the camera. Yaw and pitch in euler angles (degrees).

Kind: instance method of UserCamera

Param	Type
yaw	number
pitch	number

userCamera.setDistanceFromTarget(distance, target)

Transforms the user camera to look at a target from a specfic distance using the current rotation. This will only change the position of the user camera, not the rotation. Use this function to set the distance.

Kind: instance method of UserCamera

Param	Type
distance	number
target	vec3

userCamera.zoomBy(value)

Zoom exponentially according to this.zoomFactor and this.zoomExponent. The default zoomFactor provides good zoom speed for values from [-1,1].

Kind: instance method of UserCamera

Param	Type
value	number

userCamera.orbit(x, y)

Orbit around the target. x and y should be in radient and are added to the current rotation. The rotation around the x-axis is limited to 180 degree. The axes are inverted: e.g. if y is positive the camera will look further down.

Kind: instance method of UserCamera

Param	Type
x	number
y	number

userCamera.pan(x, y)

Pan the user camera. The axes are inverted: e.g. if y is positive the camera will move down.

Kind: instance method of UserCamera

Param	Type
x	number
y	number

userCamera.fitViewToScene(gltf, sceneIndex)

Calculates a camera position which looks at the center of the scene from an appropriate distance. This calculates near and far plane as well.

Kind: instance method of UserCamera

Param	Type
gltf	Gltf
sceneIndex	number