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], [libPath]) ⇒ 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], [libPath]) ⇒ 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
[libPath]	string	optional path to the libraries. Used to define the path to the WASM files on repackaging

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
      • .clearColor
      • .exposure
      • .usePunctual
      • .useIBL
      • .iblIntensity
      • .renderEnvironmentMap
      • .blurEnvironmentMap
      • .toneMap
      • .debugOutput
      • .environmentRotation
      • .useDirectionalLightsWithDisabledIBL
      • .internalMSAA
  • static
    • .ToneMaps
      • .KHR_PBR_NEUTRAL
      • .ACES_HILL_EXPOSURE_BOOST
      • .ACES_NARKOWICZ
      • .ACES_HILL
      • .NONE
    • .DebugOutput
      • .NONE
      • .generic
        • .UV_COORDS_0
        • .UV_COORDS_1
        • .NORMAL
        • .GEOMETRYNORMAL
        • .TANGENT
        • .BITANGENT
        • .WORLDSPACENORMAL
        • .ALPHA
        • .OCCLUSION
        • .EMISSIVE
      • .mr
        • .BASECOLOR
        • .METALLIC
        • .ROUGHNESS
      • .clearcoat
        • .CLEARCOAT_FACTOR
        • .CLEARCOAT_ROUGHNESS
        • .CLEARCOAT_NORMAL
      • .sheen
        • .SHEEN_COLOR
        • .SHEEN_ROUGHNESS
      • .specular
        • .SPECULAR_FACTOR
        • .SPECULAR_COLOR
      • .transmission
        • .TRANSMISSION_FACTOR
        • .VOLUME_THICKNESS
      • .diffuseTransmission
        • .DIFFUSE_TRANSMISSION_FACTOR
        • .DIFFUSE_TRANSMISSION_COLOR_FACTOR
      • .iridescence
        • .IRIDESCENCE_FACTOR
        • .IRIDESCENCE_THICKNESS
      • .anisotropy
        • .ANISOTROPIC_STRENGTH
        • .ANISOTROPIC_DIRECTION

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
  • .clearColor
  • .exposure
  • .usePunctual
  • .useIBL
  • .iblIntensity
  • .renderEnvironmentMap
  • .blurEnvironmentMap
  • .toneMap
  • .debugOutput
  • .environmentRotation
  • .useDirectionalLightsWithDisabledIBL
  • .internalMSAA

renderingParameters.morphing

morphing between vertices

Kind: static property of renderingParameters

renderingParameters.skinning

skin / skeleton

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.iblIntensity

image based lighting intensity

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 KHR_PBR_NEUTRAL for best color reproduction

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

renderingParameters.useDirectionalLightsWithDisabledIBL

If this is set to true, directional lights will be generated if IBL is disabled

Kind: static property of renderingParameters

renderingParameters.internalMSAA

MSAA used for cases which are not handled by the browser (e.g. Transmission)

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
  • .KHR_PBR_NEUTRAL
  • .ACES_HILL_EXPOSURE_BOOST
  • .ACES_NARKOWICZ
  • .ACES_HILL
  • .NONE

ToneMaps.KHR_PBR_NEUTRAL

Khronos PBR neutral tone mapping, see https://github.com/KhronosGroup/ToneMapping, https://modelviewer.dev/examples/tone-mapping

Kind: static property of ToneMaps

ToneMaps.ACES_HILL_EXPOSURE_BOOST

ACES sRGB RRT+ODT implementation for 3D Commerce based on Stephen Hill's implementation with a exposure factor of 1.0 / 0.6

Kind: static property of ToneMaps

ToneMaps.ACES_NARKOWICZ

fast implementation of the ACES sRGB RRT+ODT based on Krzysztof Narkowicz' implementation

Kind: static property of ToneMaps

ToneMaps.ACES_HILL

more accurate implementation of the ACES sRGB RRT+ODT based on Stephen Hill's implementation

Kind: static property of ToneMaps

ToneMaps.NONE

Linear mapping, clamped at 1.0 per channel

Kind: static property of ToneMaps

GltfState.DebugOutput

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

Kind: static property of GltfState

• .DebugOutput
  • .NONE
  • .generic
    • .UV_COORDS_0
    • .UV_COORDS_1
    • .NORMAL
    • .GEOMETRYNORMAL
    • .TANGENT
    • .BITANGENT
    • .WORLDSPACENORMAL
    • .ALPHA
    • .OCCLUSION
    • .EMISSIVE
  • .mr
    • .BASECOLOR
    • .METALLIC
    • .ROUGHNESS
  • .clearcoat
    • .CLEARCOAT_FACTOR
    • .CLEARCOAT_ROUGHNESS
    • .CLEARCOAT_NORMAL
  • .sheen
    • .SHEEN_COLOR
    • .SHEEN_ROUGHNESS
  • .specular
    • .SPECULAR_FACTOR
    • .SPECULAR_COLOR
  • .transmission
    • .TRANSMISSION_FACTOR
    • .VOLUME_THICKNESS
  • .diffuseTransmission
    • .DIFFUSE_TRANSMISSION_FACTOR
    • .DIFFUSE_TRANSMISSION_COLOR_FACTOR
  • .iridescence
    • .IRIDESCENCE_FACTOR
    • .IRIDESCENCE_THICKNESS
  • .anisotropy
    • .ANISOTROPIC_STRENGTH
    • .ANISOTROPIC_DIRECTION

DebugOutput.NONE

standard rendering - debug output is disabled

Kind: static property of DebugOutput

DebugOutput.generic

generic debug outputs

Kind: static property of DebugOutput

• .generic
  • .UV_COORDS_0
  • .UV_COORDS_1
  • .NORMAL
  • .GEOMETRYNORMAL
  • .TANGENT
  • .BITANGENT
  • .WORLDSPACENORMAL
  • .ALPHA
  • .OCCLUSION
  • .EMISSIVE

generic.UV_COORDS_0

output the texture coordinates 0

Kind: static property of generic

generic.UV_COORDS_1

output the texture coordinates 1

Kind: static property of generic

generic.NORMAL

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

Kind: static property of generic

generic.GEOMETRYNORMAL

output the normal from the TBN

Kind: static property of generic

generic.TANGENT

output the tangent from the TBN

Kind: static property of generic

generic.BITANGENT

output the bitangent from the TBN

Kind: static property of generic

generic.WORLDSPACENORMAL

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

Kind: static property of generic

generic.ALPHA

output the alpha value

Kind: static property of generic

generic.OCCLUSION

output the occlusion value

Kind: static property of generic

generic.EMISSIVE

output the emissive value

Kind: static property of generic

DebugOutput.mr

metallic roughness

Kind: static property of DebugOutput

• .mr
  • .BASECOLOR
  • .METALLIC
  • .ROUGHNESS

mr.BASECOLOR

output the base color value

Kind: static property of mr

mr.METALLIC

output the metallic value from pbr metallic roughness

Kind: static property of mr

mr.ROUGHNESS

output the roughness value from pbr metallic roughness

Kind: static property of mr

DebugOutput.clearcoat

KHR_materials_clearcoat

Kind: static property of DebugOutput

• .clearcoat
  • .CLEARCOAT_FACTOR
  • .CLEARCOAT_ROUGHNESS
  • .CLEARCOAT_NORMAL

clearcoat.CLEARCOAT_FACTOR

output the clear coat strength

Kind: static property of clearcoat

clearcoat.CLEARCOAT_ROUGHNESS

output the clear coat roughness

Kind: static property of clearcoat

clearcoat.CLEARCOAT_NORMAL

output the clear coat normal

Kind: static property of clearcoat

DebugOutput.sheen

KHR_materials_sheen

Kind: static property of DebugOutput

• .sheen
  • .SHEEN_COLOR
  • .SHEEN_ROUGHNESS

sheen.SHEEN_COLOR

output the sheen color

Kind: static property of sheen

sheen.SHEEN_ROUGHNESS

output the sheen roughness

Kind: static property of sheen

DebugOutput.specular

KHR_materials_specular

Kind: static property of DebugOutput

• .specular
  • .SPECULAR_FACTOR
  • .SPECULAR_COLOR

specular.SPECULAR_FACTOR

output the specular strength

Kind: static property of specular

specular.SPECULAR_COLOR

output the specular color

Kind: static property of specular

DebugOutput.transmission

KHR_materials_transmission

Kind: static property of DebugOutput

• .transmission
  • .TRANSMISSION_FACTOR
  • .VOLUME_THICKNESS

transmission.TRANSMISSION_FACTOR

output the transmission strength

Kind: static property of transmission

transmission.VOLUME_THICKNESS

output the volume thickness

Kind: static property of transmission

DebugOutput.diffuseTransmission

KHR_materials_diffuse_tranmission

Kind: static property of DebugOutput

• .diffuseTransmission
  • .DIFFUSE_TRANSMISSION_FACTOR
  • .DIFFUSE_TRANSMISSION_COLOR_FACTOR

diffuseTransmission.DIFFUSE_TRANSMISSION_FACTOR

output the diffuse tranmission strength

Kind: static property of diffuseTransmission

diffuseTransmission.DIFFUSE_TRANSMISSION_COLOR_FACTOR

output the diffuse tranmission color factor

Kind: static property of diffuseTransmission

DebugOutput.iridescence

KHR_materials_iridescence

Kind: static property of DebugOutput

• .iridescence
  • .IRIDESCENCE_FACTOR
  • .IRIDESCENCE_THICKNESS

iridescence.IRIDESCENCE_FACTOR

output the iridescence strength

Kind: static property of iridescence

iridescence.IRIDESCENCE_THICKNESS

output the iridescence thickness

Kind: static property of iridescence

DebugOutput.anisotropy

KHR_materials_anisotropy

Kind: static property of DebugOutput

• .anisotropy
  • .ANISOTROPIC_STRENGTH
  • .ANISOTROPIC_DIRECTION

anisotropy.ANISOTROPIC_STRENGTH

output the anisotropic strength

Kind: static property of anisotropy

anisotropy.ANISOTROPIC_DIRECTION

output final direction as defined by the anisotropyTexture and rotation

Kind: static property of anisotropy

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, libPath)
  • .loadGltf(gltfFile, [externalFiles]) ⇒ Promise
  • .loadEnvironment(environmentFile, [lutFiles]) ⇒ Promise
  • .initKtxLib([externalKtxLib])
  • .initDracoLib([externalDracoLib])

new ResourceLoader(view, libPath)

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	Default	Description
view	Object		the GltfView for which the resources are loaded
libPath	String	./libs/	path to the lib folder. This can be used to find the WASM files if sample viewer is repackaged

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)
  • .resetView(gltf, sceneIndex)
  • .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.resetView(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

userCamera.fitViewToScene(gltf, sceneIndex)

Fit view to updated canvas size without changing rotation if distance is incorrect

Kind: instance method of UserCamera

Param	Type
gltf	Gltf
sceneIndex	number