Viewer Advanced Usage
The Babylon Viewer aims to make the most common model viewing scenarios simple and robust. That said, inevitably there will be specific needs for specific use cases, and as such the Babylon Viewer supports several routes for customization.
Configuring the Babylon Viewer
Viewer
When constructing a low-level Viewer, pass in an options object to specify various initialization-time configurations.
CreateViewerForCanvas
Similarly, when calling CreateViewerForCanvas, the same options can be passed in.
HTML3DElement
When using the HTML3DElement (<babylon-viewer>), the same options can again be passed to the constructor. However, an HTML3DElement instance is typically created by placing a <babylon-viewer> element within an HTML page, so constructor arguments cannot be passed. When it is necessary to provide options for the HTML3DElement, use the ConfigureCustomViewerElement function to create a custom element with a unique name and the desired options. For example:
ConfigureCustomViewerElement("my-babylon-viewer", { limitDeviceRatio: 2 });<my-babylon-viewer source="..."></my-babylon-viewer>In this example, when a my-babylon-viewer element is used, it will have a configuration that sets limitDeviceRatio to 2, meaning the maximum render resolution will be limited on high-resolution devices with a DPR greater than 2.
Accessing the full Babylon API through the Viewer's public API
The primary public entry point from the HTML3DElement (<babylon-viewer>) to the Babylon API is the viewerDetails property and the associated viewerready event (which fires any time the viewerDetails changes). Any time the HTML3DElement is disconnected from the DOM, the underlying viewerDetails is disposed, and any time it is (re)connected to the DOM, the viewerDetails is (re)created. However, it is created asynchronously, so using the viewerready event is a way to know when the engine, scene, etc. have been recreated.
Example 1 - Drag & Drop
This example uses the viewerDetails property to access the underlying Viewer and its loadModel function to load from a File object rather than a URL:
See the Pen Babylon Viewer Annotations - Custom by BabylonJS.
Example 2 - Wireframe
This example uses the modelchange event and the viewerDetails property to access the materials of the loaded model to enable wireframe rendering:
See the Pen Babylon Viewer Annotations - Custom by BabylonJS.
Customizing the Babylon Viewer through the protected API
All layers of the Babylon Viewer support subclassing as a means of customization. Subclasses can access the protected API of each layer.
The low-level Viewer exposes many protected APIs and allows multiple models to be loaded simultaneously.
When calling CreateViewerForCanvas, it is also possible to pass in a Viewer subclass. CreateViewerForCanvas will use this subclass when creating the Viewer instance.
Similarly, when subclassing ViewerElement (the base class of HTML3DElement), it is possible to pass in a Viewer subclass. Additionally, ViewerElement exposes protected APIs that allow for additional customization.
