RenderInstanceGroups ( )

Parameters

None.

Description

Returns how many multi-instance groups the renderer formed in the last completed frame.

Read this as "how many kinds of repeated object got merged". Every group is one set of surfaces that matched on everything the renderer needs them to share: the same mesh, the same shader, the same textures and texture blend modes, the same brush state, the same depth and blend settings, the same render segment and the same viewport. A scene with grass, rocks and fence posts all repeating should report three.

The number is most useful next to RenderInstances. A handful of groups holding thousands of instances is the shape you want. Many small groups usually means something is splitting your repeats needlessly - a per-copy EntityTexture or EntityColor, a different EntityOrder on some of them, or a mix of alpha and opaque materials in what should be one batch.

On the current renderer each merged draw is counted as exactly one group, so this returns the same figure as RenderInstancedDraws. The two are reported separately because they answer different questions, and a group that is split by the 4,096 instance draw limit only counts once here.

Gotcha: this describes the most recently completed frame's main colour pass, so read it after Flip. Groups only ever contain surfaces that share mesh data, so entities built from separate LoadMesh or CreateCube calls never join one.

Requires Extended mode.

See also: RenderInstancedDraws, RenderInstances, RenderDrawCalls, RenderSubmittedDraws, DrawRenderStats.

Example

; RenderInstanceGroups Example
; ----------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,6,-20
CameraClsColor camera,20,30,50

light=CreateLight()
RotateEntity light,45,45,0

ground=CreatePlane()
EntityColor ground,60,80,55

; Three mesh families - copies within a family are compatible, so each
; visible family forms one multi-instance group
crate=CreateCube()
ScaleMesh crate,0.5,0.5,0.5
EntityColor crate,180,90,60

orb=CreateSphere(8)
ScaleMesh orb,0.6,0.6,0.6
EntityColor orb,80,200,255

post=CreateCylinder(8)
ScaleMesh post,0.3,1.2,0.3
PositionMesh post,0,1.2,0
EntityColor post,120,220,90

Dim crates(39)
Dim orbs(39)
Dim posts(39)
For n=0 To 39
    crates(n)=CopyEntity(crate)
    PositionEntity crates(n),(n Mod 8)*4-14,0.5,(n/8)*4+4
    orbs(n)=CopyEntity(orb)
    PositionEntity orbs(n),(n Mod 8)*4-13,3,(n/8)*4+4
    posts(n)=CopyEntity(post)
    PositionEntity posts(n),(n Mod 8)*4-12,0,(n/8)*4+4
Next
HideEntity crate
HideEntity orb
HideEntity post

crates_on=True
orbs_on=True
posts_on=True

While Not KeyDown(1)

    ; Keys 1/2/3 toggle each family - the group count follows
    If KeyHit(2)
        crates_on=Not crates_on
        For n=0 To 39
            If crates_on Then ShowEntity crates(n) Else HideEntity crates(n)
        Next
    EndIf
    If KeyHit(3)
        orbs_on=Not orbs_on
        For n=0 To 39
            If orbs_on Then ShowEntity orbs(n) Else HideEntity orbs(n)
        Next
    EndIf
    If KeyHit(4)
        posts_on=Not posts_on
        For n=0 To 39
            If posts_on Then ShowEntity posts(n) Else HideEntity posts(n)
        Next
    EndIf

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    ; Compatible groups that contained multiple instances last frame
    Text 0,0,"1/2/3: toggle crates/orbs/posts   Arrows: camera   Esc: exit"
    Text 0,20,"RenderInstanceGroups() = "+RenderInstanceGroups()
    Text 0,40,"Each visible family of 40 copies forms one group"

    Flip

Wend

End

Index

Blitz3D+ Command Reference

RenderInstanceGroups ( )

Parameters

Description

Example