TiledGraphicsProvider

The iTwin.js display system provides out-of-the-box support for tiles from a wide variety of sources, but in some cases an application may wish to display their own custom graphics in a Viewport. For relatively simple graphics, view decorations are often an appropriate choice. However, for more complex graphics, the application can instead implement a TiledGraphicsProvider to supply tiles to be rendered as part of the scene.

To register your provider with a viewport, use Viewport.addTiledGraphicsProvider; to unregister it, use Viewport.dropTiledGraphicsProvider. Note that a given provider can be registered with any number of viewports at any given time.

The TiledGraphicsProvider interface defines only three methods, and all but one of these are optional:

• TiledGraphicsProvider.forEachTileTreeRef: This method enables the display system to iterate all of the TileTreeReferences exposed by the provider and execute a function on each one. Your implementation should simply invoke the supplied function once for each tile tree reference associated with the specified Viewport.
• TiledGraphicsProvider.addToScene: This method is invoked when it is time to draw your tiles into a viewport. If your provider does not implement this method, then forEachTileTreeRef will be invoked to call TileTreeReference.addToScene on each reference.
• TiledGraphicsProvider.isLoadingComplete: This method returns true if all of the TileTrees required by your provider are ready for use. You may need to implement this method if you must perform some asynchronous work before your tile trees are ready; otherwise, forEachTileTreeRef will be invoked to call TileTreeReference.isLoadingComplete on each reference.

Of course, implementing forEachTileTreeRef implies that you will instantiate one or more TileTreeReferences, which in turn means you will probably need to implement subclasses of TileTree and/or Tile. This example provides a sample implementation of a TiledGraphicsProvider capable of animating an "exploded" view of a set of elements.