Add support for tile selection state debugging. #1568
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This requires CesiumGS/cesium-native#1032, so merge that first.
This PR adds a new
CESIUM_DEBUG_TILE_STATES
feature that can be activated by uncommenting the new line inCesiumRuntime.build.cs
. When enabled and running in Play-in-Editor mode, every tileset will log the selection state of every loaded tile to a SQLite database every frame.This is really useful for debugging tile selection problems. Let's say we have a tile selection problem that's perhaps a bit hard to reproduce, and even harder to capture in the moment so we can inspect it in the debugger. Here's what we can do with this new feature enabled...
First, enable `Log Selection Stats on the tileset, and make sure the Output Log is visible. That will ensure that the "Tileset Frame" is visible.
Next, record a video of the problem being reproduced in Play-in-Editor mode. It may help to set
t.maxfps 30
in the console so that the video is better able to capture every render frame. If you're using the Windows Game Bar to record, increasing the video frame rate from 30 to 60 may help with this, too:Exit Play-in-Editor to minimize the amount that is written to the database.
Now you can look through the video for the moment that something visibly went wrong, and look at the "Tileset Frame" number to see on what frame it went wrong. VLC has the ability to step through single frames of a video, which is handy here.
Now open the tile selection database in the sqlite3 command-line tool. The
TileSelectionFrames
table has the following columns:Pointer
- TheTile
pointer, which serves as a unique ID for the tile.FrameNumber
- The "Tileset Frame" at which this state was recorded.TileID
- The readable version of the tile's ID. This will be the URL for a regular tileset.json, or a tile ID likeL2-X1-Y2
for quantized-mesh and implicit tiles.SelectionStateFrameNumber
- The last "Tileset Frame" in which the selection state was updated. If this is less thanFrameNumber
, it means this tile wasn't visited at all this frame.SelectionState
- The selection state for this tile on theSelectionStateFrameNumber
, such as Rendered, Refined, Culled, RenderedAndKicked, etc. This is a foreign key into theTileSelectionStates
table which has descriptive names.IsRenderable
- Whether or not this tile was considered renderable this frame. 0 is No and 1 is Yes, but it's also a foreign key into theIsRenderableStates
table.So let's say we can see that something went wrong on frame 441. We can run a query like this:
And we'll get rows like this:
We can also inspect the states on prior frames, or narrow down to specific tiles by adding something like
TileID LIKE 'L16-X21036-Y46552'
to the where clause.It's also possible to modify
DebugTileStateDatabase.cpp
to capture more information about the tile, such as its load state or whatever else is useful for what we're trying to debug.