 | |
Instanced | |
Inheritance HierarchyAb4d.SharpEngine.CoreComponentBase
Ab4d.SharpEngine.CoreInitializedSceneComponent
Ab4d.SharpEngine.SceneNodesSceneNode
Ab4d.SharpEngine.SceneNodesRenderedNode
Ab4d.SharpEngine.SceneNodesInstancedMeshNode
Namespace: Ab4d.SharpEngine.SceneNodes
Assembly: Ab4d.SharpEngine (in Ab4d.SharpEngine.dll) Version: 2.0.8956+4c7684e186ca1be74e7a284fbe739d9a1b843d3c
Syntaxpublic class InstancedMeshNode : RenderedNode, IRayHitTestedObject
The InstancedMeshNode type exposes the following members.
Constructors| Name | Description | |
|---|---|---|
 | InstancedMeshNode | Constructor |
| InstancedMeshNode(String) | Constructor |
| InstancedMeshNode(Mesh, String) | Constructor |
| InstancedMeshNode(Mesh, WorldColorInstanceData, String) | Constructor |
Properties| Name | Description | |
|---|---|---|
 | InstancesCount | Gets or sets number of rendered instances. This value is automatically set from the SetInstanceData method to the length of the InstancesData array. But user can change the value to render just part of the instances. Changing this property will recalculate the bounding box of this SceneNode. To prevent potentially slow recalculation, use the SetInstancesRange(Int32, Int32, BoundingBox) method. |
| IsBackFaceMaterial | Gets or sets a Boolean that specifies if this InstancedMeshNode is rendering front or back faces of the mesh. Default value is false which means that front face materials are rendered. This value need to be set before the InstancedMeshNode is initialized. |
| IsSolidColorMaterial | Gets or sets a Boolean that specifies if instanced objects are rendered with a solid color (without any shading based on lighting calculations). Default value is false. |
| IsUpdatingBounds | Gets or sets a Boolean that specifies if this InstancedMeshNode is automatically updating its BoundingBox value. Default value is true. |
| IsUsingSingleObjectColor | Gets a Boolean that specified if single color is used for all instance. This is enabled by calling UseSingleObjectColor(Color4) method and disabled by calling UseInstanceObjectColor method. |
| Mesh | Gets or sets a mesh that is used for each instance. |
| StartInstanceIndex | StartInstanceIndex can be set to an index that will render only instances from the specified start index on. Changing this property will recalculate the bounding box of this SceneNode. To prevent potentially slow recalculation, use the SetInstancesRange(Int32, Int32, BoundingBox) method. |
| UseAlphaBlend | Gets or sets a Boolean that specifies if alpha blending is used when rendering model instances. This can be used to render semi-transparent objects. Default value is false. This property is used only when instance color is used (not when UseSingleObjectColor(Color4) is called). |
Methods| Name | Description | |
|---|---|---|
| CollectRenderingItems |
CollectRenderingItems
(Overrides SceneNodeCollectRenderingItems(RenderingContext)) |
 | Dispose | (Overrides SceneNodeDispose(Boolean)) |
| GetCenterPosition |
Returns center position of this InstancedMeshNode.
When applyTransformation is true (by default), then center position is also transformed by Transform.
(Overrides RenderedNodeGetCenterPosition(Boolean, Boolean)) |
| GetClosestHitResult | GetClosestHitResult method returns a RayHitTestResult with the closest triangle hit by the specified ray. When no triangle is hit, null is returned. |
| GetLocalBoundingBox |
Gets the BoundingBox of this SceneNode in local coordinates.
The BoundingBox is transformed by transformation on this SceneNode but not by parent's transformations.
(Overrides SceneNodeGetLocalBoundingBox(Boolean)) |
| GetNextHitResult | GetNextHitResult method continues hit testing from the previously returned hit test and returns a RayHitTestResult with the next hit triangle (not necessary the next closest triangle) or null if no other triangle is hit. This method can be used to get all hit results. |
| GetRenderingLayer |
GetRenderingLayer
(Overrides RenderedNodeGetRenderingLayer(Material, Mesh)) |
| GetWorldColorInstancesData | Returns an array of WorldColorInstanceData structs that define the instances data that were set by calling the SetInstancesData(WorldColorInstanceData) method. |
| OnInitializeSceneResources |
Initializes resources with the specified Scene and GpuDevice.
This method can be override and is called from InitializeSceneResources(Scene) method.
(Overrides InitializedSceneComponentOnInitializeSceneResources(Scene, VulkanDevice)) |
| OnUpdate |
OnUpdate
(Overrides SceneNodeOnUpdate) |
| OnWorldMatrixChanged |
OnWorldMatrixChanged
(Overrides SceneNodeOnWorldMatrixChanged) |
| SetInstancesData(WorldColorInstanceData) | SetInstancesData method sets an array of WorldColorInstanceData structs that define the world transformations (positions, scales, rotations) and colors or instanced geometry objects. Calling this method sets StartInstanceIndex to zero and InstancesCount to the number of elements in the instancesData array. After each change of InstancesData user must call UpdateInstancesData(Boolean) or UpdateInstancesData(BoundingBox) methods. This method also calculates a new BoundingBox from the instancesData. If you know the BoundingBox of all mesh instances, call the SetInstancesData(WorldColorInstanceData, BoundingBox) method. |
| SetInstancesData(WorldColorInstanceData, BoundingBox) | SetInstancesData method sets an array of WorldColorInstanceData structs that define the world transformations (positions, scales, rotations) and colors or instanced geometry objects. Calling this method sets StartInstanceIndex to zero and InstancesCount to the number of elements in the instancesData array. After each change of InstancesData user must call UpdateInstancesData(Boolean) or UpdateInstancesData(BoundingBox) methods. This method also gets the BoundingBox of all mesh instances. If you do not know the BoundingBox call the SetInstancesData(WorldColorInstanceData) method. |
| SetInstancesRange | SetInstancesRange method sets both StartInstanceIndex and InstancesCount and provides the new bounding box to prevent recalculating bounding box by this class. |
| UpdateInstancesData(Boolean) | UpdateInstancesData recreates the instances data buffer from the array of WorldColorInstanceData that was set by calling the SetInstancesData(WorldColorInstanceData) method. When the BoundingBox has changed and you know the new bounding box, call the UpdateInstancesData(BoundingBox) to prevent calculating it from the instances data. |
| UpdateInstancesData(BoundingBox) | UpdateInstancesData recreates the instances data buffer from the array of WorldColorInstanceData that was set by calling the SetInstancesData(WorldColorInstanceData) method. This method also sets new bounding box of all mesh instances (without the transformation that is applied to this SceneNode). |
| UpdateLocalBoundingBox |
UpdateLocalBoundingBox
(Overrides SceneNodeUpdateLocalBoundingBox) |
| UpdateRenderingItemMesh | |
| UseInstanceObjectColor | UseInstanceObjectColor method can be called after calling the UseSingleObjectColor(Color4). After calling this method, the object colors are get from diffuse color defined in instances data array. |
| UseSingleObjectColor | When UseSingleObjectColor is called, the specified objectColor is used as diffuse color for all instances. This overrides the color defined in the instances data. When color's alpha value is less than 1, then alpha blending is used. To use instance color after calling UseSingleObjectColor, call the UseInstanceObjectColor method. |
Fields| Name | Description | |
|---|---|---|
 | material | StandardMaterial that is used for this InstancedMeshNode |
| renderingItem | RenderingItem that is generated in CollectRenderingItems(RenderingContext) |
RemarksInstancedMeshNode is a SceneNode that can be used to render a single Mesh multiple times as instances where each instance can have its own color and its own world matrix (defines scale, rotation and translation).
The mesh that is rendered with this InstancedMeshNode can be defined in a constructor or by setting the Mesh property.
The data about each instance that will be rendered are specified by calling the SetInstancesData method. The method takes an array of structs that define individual instance data. For example the SetInstancesData(WorldColorInstanceData) method takes an array of WorldColorInstanceData structs. Each struct defines a Matrix4x4 and a Color4. Matrix can be used to position the object (by defining the M41, M42, M43 fields), scale of the object (by defining M11, M22, M33) and rotation (with using method on the Matrix4x4 class). Color defines the color of this instance - same as using DiffuseMaterial with SolidColorBrush. If color has alpha value less the 1 (is semi-transparent), then UseAlphaBlend property must be set to true (see below for more information on how to render semi-transparent instances).
If the instance world matrix or color values are changed, then UpdateInstancesData(Boolean) or UpdateInstancesData(BoundingBox) methods must be called to update the buffers that are used by the graphics card.
To render back faces (back side of triangles), set the IsBackFaceMaterial to true.
By default the colors of the instances is defined in the instances data, but by calling the UseSingleObjectColor(Color4) method it is possible to set a color that is used to render all instances. To switch back to using color from instances data call UseInstanceObjectColor.
To render instances without any lighting calculations (with a solid color without any shading) set the IsSolidColorMaterial to true.
Rendering semi-transparent instances
When instances use semi-transparent colors (color's alpha is less than 1), the UseAlphaBlend property must be set to true. This will use alpha bending to blend the semi-transparent colors with already rendered 3D objects.
If only some objects have transparent colors and the colors do not change, then it is recommended to split the instance objects into two InstancedMeshGeometryVisual3D objects - one with solid and the other with semi-transparent instances.
Because semi-transparent objects are rendered with using alpha blending (blending semi-transparent color with already rendered objects), the order of positions need to be such, that the instances that farther away from the camera need to be added before those that are closer to the camera.
See Also