NextVersion

core/frontend/src/render/RenderSystem.ts

@@ -227,6 +227,10 @@ export interface RenderAreaPattern extends IDisposable, RenderMemory.Consumer {
 /** Contains the WebGL resources necessary to draw multiple [[Instance]]s of a [[GraphicTemplate]] using [instanced rendering](https://webglfundamentals.org/webgl/lessons/webgl-instanced-drawing.html).
  * Use [[RenderSystem.createRenderInstances]] to create one.
  * The instances may be associated with [Feature]($common)s, in which case those features override any defined in the template itself.
+ * Example usage:
+ * ```ts
+ * [[include:Gltf_Instancing]]
+ * ```
  * @beta
  */
 export interface RenderInstances {

docs/changehistory/NextVersion.md

@@ -6,10 +6,13 @@ publish: false
 Table of contents:
 
 - [Revert timeline changes](#revert-timeline-changes)
-- [Calculated properties specification enhancements](#calculated-properties-specification-enhancements)
-- [API Deprecations](#api-deprecations)
+- [Display](#display)
+  - [Instancing](#instancing)
+- [Presentation](#presentation)
+  - [Calculated properties specification enhancements](#calculated-properties-specification-enhancements)
+  - [API Deprecations](#api-deprecations)
 
-### Revert timeline changes
+## Revert timeline changes
 
 At present, the sole method to reverse a defective changeset is to remove it from the iModel hub, which can lead to numerous side effects. A preferable approach would be to reverse the changeset in the timeline and introduce it as a new changeset. Although this method remains intrusive and necessitates a schema lock, it is safer because it allows for the reversal to restore previous changes, ensuring that nothing is permanently lost from the timeline.
 
@@ -23,6 +26,26 @@ Some detail and requirements are as following.
 - If no description is provided after a revert, a default description for the changeset will be created and pushed, which releases the schema lock.
 - Schema changes are not reverted during SchemaSync, or they can be optionally skipped when SchemaSync is not utilized.
 
+## Display
+
+### Instancing
+
+Some scenarios involve displaying the same basic graphic repeatedly. For example, imagine you are writing a [Decorator]($frontend) that displays stop signs at many intersections along a road network. You might create one [RenderGraphic]($frontend) for each individual stop sign and draw them all, but doing so would waste a lot of memory by duplicating the same geometry many times, and negatively impact your frame rate by invoking many draw calls.
+
+WebGL provides [instanced rendering](https://webglfundamentals.org/webgl/lessons/webgl-instanced-drawing.html) to support this kind of use case. You can define a single representation of the stop sign graphic, and then tell the renderer to draw it many times at different locations, orientations, and scales. iTwin.js now provides APIs that make it easy for you to create instanced graphics:
+
+- [GraphicTemplate]($frontend) defines what the graphic should look like. You can obtain a template from [GraphicBuilder.finishTemplate]($frontend), [RenderSystem.createTemplateFromDescription]($frontend), or [readGltfTemplate]($frontend).
+- [RenderInstances]($frontend) defines the set of instances of the template to draw. In addition to a [Transform]($geometry), each instance can also override aspects of the template's appearance like color and line width, along with a unique [Feature]($common) to permit each instance to behave as a discrete entity. You can create a `RenderInstances` using [RenderInstancesParamsBuilder]($frontend).
+- [RenderSystem.createGraphicFromTemplate]($frontend) produces a [RenderGraphic]($frontend) from a graphic template and a set of instances.
+
+`GraphicTemplate` and `RenderInstances` are both reusable - you can produce multiple sets of instances of a given template, and use the same set of instances with multiple different templates.
+
+For the stop sign example described above, you might have a [glTF model](https://en.wikipedia.org/wiki/GlTF) representing a stop sign and an array containing the position of each stop sign. You could t hen use a function like the following to produce a graphic that draws the stop sign at each of those positions.
+
+```ts
+[[include:Gltf_Instancing]]
+```
+
 ## Presentation
 
 ### Calculated properties specification enhancements

example-code/snippets/src/frontend/Instancing.ts

@@ -6,12 +6,8 @@
 import { IModelApp, IModelConnection, readGltfTemplate, RenderGraphic, RenderInstancesParamsBuilder } from "@itwin/core-frontend";
 import { Point3d, Transform } from "@itwin/core-geometry";
 
-// __PUBLISH_EXTRACT_START__
-/** Create a graphic that renders the specified glTF model at multiple positions.
- * @param gltf The raw glTF describing the model.
- * @param positions The locations at which to draw each instance of the model.
- * @param iModel The iModel to be associated with the graphic.
- */
+// __PUBLISH_EXTRACT_START__ Gltf_Instancing
+/** Create a graphic that renders multiple instances of a glTF model. */
 export async function instanceGltfModel(gltf: Uint8Array | object, positions: Point3d[], iModel: IModelConnection): Promise<RenderGraphic> {
   // Decode the raw glTF as an instanceable  template.
   const template = (await readGltfTemplate({ gltf, iModel }))?.template;