Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for tile selection state debugging. #1568

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

kring
Copy link
Member

@kring kring commented Dec 9, 2024

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 in CesiumRuntime.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:
image

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 - The Tile 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 like L2-X1-Y2 for quantized-mesh and implicit tiles.
  • SelectionStateFrameNumber - The last "Tileset Frame" in which the selection state was updated. If this is less than FrameNumber, it means this tile wasn't visited at all this frame.
  • SelectionState - The selection state for this tile on the SelectionStateFrameNumber, such as Rendered, Refined, Culled, RenderedAndKicked, etc. This is a foreign key into the TileSelectionStates 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 the IsRenderableStates table.

So let's say we can see that something went wrong on frame 441. We can run a query like this:

SELECT
  FrameNumber,
  Pointer,
  TileID,
  SelectionStateFrameNumber,
  TileSelectionStates.Name,
  IsRenderableStates.Name
FROM TileSelectionFrames
INNER JOIN TileSelectionStates ON SelectionState=TileSelectionStates.Value
INNER JOIN IsRenderableStates ON IsRenderable=IsRenderableStates.Value
WHERE FrameNumber=441;

And we'll get rows like this:

Frame Number Pointer TileID SelectionStateFrameNumber SelectionState IsRenderable
441 6274942445792 L16-X21034-Y46555 441 RenderedAndKicked Renderable
441 6274942447424 L16-X21035-Y46555 441 RenderedAndKicked Renderable
441 6274900457088 L14-X5259-Y11638 441 Refined Renderable
441 6274900469792 L15-X10518-Y23276 441 Rendered Not Renderable
441 6274900476960 L16-X21036-Y46552 441 RenderedAndKicked Not Renderable
441 6274900478592 L16-X21037-Y46552 441 RenderedAndKicked Renderable

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant