Blitz3D+ Command Reference

RenderGPUTime# ( )

Parameters

None.

Description

Returns the GPU milliseconds for a recently completed frame, or -1 when no reading is available.

RenderGPUTime reports how long the graphics card actually spent on a frame, measured with GPU timestamps. The query is non-blocking - the engine never stalls waiting for the GPU to answer - so the number describes a frame a beat or two behind the one you just presented, and the call is safe to make every frame.

Expect -1 sometimes, by design: before the first timestamps complete in the opening frames, and on systems where the GPU or driver cannot supply timestamps at all, where it stays -1 for good. Always handle the -1 case rather than dividing by the result. DrawRenderStats shows the same situation as "n/a".

Its headline use is settling the classic question: CPU-bound or GPU-bound? If RenderGPUTime dwarfs RenderCPUTime, the card is the bottleneck - look at resolution, overdraw, shadows and post effects. If it is small while FrameTime is big, the GPU is coasting and the time is going elsewhere.

Requires Extended mode.

See also: RenderCPUTime, FrameTime, RenderTriangles, DrawRenderStats.

Example

; RenderGPUTime Example
; ---------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,3,-14

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

; An asteroid ring the player can switch off to lighten the GPU's work
hub=CreatePivot()
Dim rocks(29)
For n=0 To 29
    rocks(n)=CreateSphere(24)
    ScaleEntity rocks(n),0.6,0.6,0.6
    PositionEntity rocks(n),6*Cos(n*12),2*Sin(n*47),6*Sin(n*12)
    EntityParent rocks(n),hub
    EntityColor rocks(n),130,120,110
Next

heavy=True

While Not KeyDown(1)

    ; Space toggles the asteroid ring on and off
    If KeyHit(57) Then
        heavy=Not heavy
        For n=0 To 29
            If heavy Then ShowEntity rocks(n) Else HideEntity rocks(n)
        Next
    EndIf

    TurnEntity hub,0,0.5,0

    ; 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

    ; RenderGPUTime is non-blocking and returns -1 until a timestamp is ready
    gpu#=RenderGPUTime()
    Text 0,0,"Arrow keys: move camera   Space: toggle asteroids   Esc: exit"
    If gpu<0 Then Text 0,20,"RenderGPUTime() = -1 (no completed GPU timestamp yet)" Else Text 0,20,"RenderGPUTime() = "+gpu+" ms of GPU work"

    Flip

Wend

End

Index