Synopsis

ramses-scene-viewer-PLATFORM [options] -s SCENE_FILE

PLATFORM typically means "windows-wgl-4-2-core" on Windows and "x11-egl-es-3-0" on Linux desktop.

Description

ramses-scene-viewer is a tool to display and inspect Ramses scene files (e.g. created by ramses::Scene::saveToFile()). It helps to find errors and unused objects. The inspection GUI visualizes the relations between the scene objects and allows to do simple modifications.

The window size is auto-detected based on the first camera viewport in the scene. This can be overridden by the options -w, –width or -h, –height

Inspection GUI

The inspection GUI provides different views on the scene objects (described in the sections below).

These features are common to all object types:

scene objects are displayed in the format Type[id]: name and can be unfolded to show the details / relationships.
The relationships are bi-directional. Reverse lookups are shown in Used by tree items.
Most scene object properties can be modified. The modification is immediately applied to the rendered scene.
grayed out objects are detected as "unnecessary". This actually means different things depending on the object type, e.g.
- a Node might not contain any MeshNode
- a MeshNode might not be be part of a RenderGroup
- a ResourceObject might use the same underlying LowLevel-Resource than another ResourceObject
red objects contain an error message (unless validation is switched off by command line)

File

Allows to save the current scene to another file. This is mainly useful to store scene modifications done in the UI.

Scene objects

Provides a list of all scene objects grouped by type. For each type the number of instances is displayed. Types with zero instances are not listed.

The objects can be filtered by name. It's also possible to apply negative filtering by a prefix "-".

Node hierarchy

Shows the node tree. The first layer only shows nodes without parent (root nodes). Children can be unfolded.

Resources

Shows the total number of resources and the amount of memory that they are consuming. "Not loaded" resources are currently not used by any render pass (possibly because some parent mesh node is switched off).

Additionally all resource objects are listed in descending size order. The "Display limit" can be used to only show the largest x resources and their consumed memory.

Grayed out resources are typically duplicates, i.e. they refer to the same underlying byte buffer identified by a hash value. If that's the case, the duplicates are listed in the details. This is not indicating a problem because the underlying data will only be stored once in memory.

Texture2D objects can be exported to png (not all texture formats may be supported though). The list of all Texture2D objects can be copied to clipboard (CSV-format) for further external processing.

Render hierarchy

Shows the render order of RenderPasses, RenderGroups and MeshNodes. The order can be modified in the UI, but will not be applied immediately to the scene. Use the "refresh" button to apply changes. This will also reorder the lists.

Objects with errors/warnings

Contains a list of objects where the scene validation found an issue. If the scene validation did not run (see -nv option) or no error was found, this section will not be displayed.

Options

-s, –scene SCENE_FILE

The scene file that shall be loaded (required argument).

-nv, –no-validation

Disable scene validation.

Scene validation noticably increases startup time. If the validation state is not needed or is already known, it might make sense to skip this step.

-vd, –validation-output-directory DIRECTORY

If this option is provided the ramses-scene-viewer will dump the validation information and the summary of unused scene objects to this directory.

-x, –screenshot-file FILE

Store a screenshot to FILE and exit. The file is stored in png format.

-ns, –no-skub

Disable skub (skipping of unmodified buffer).

Rendering will be triggered unconditionally for every frame. This is e.g. useful if the scene shall be analysed with a GPU profiling tool.

-gui, –gui MODE

Configure the inspection gui mode (default: on)

Possible values:

on the scene is rendered to an offscreen buffer. The inspection gui can be displayed as an overlay window or the scene can be displayed in a scalable window side-by-side.
off The inspection gui is switched off
overlay The scene is directly rendered to the window (no offscreen buffer). The inspection gui is displayed as an overlay window.

Note: The gui is automatically switched off in screenshot mode (-x, –screenshot).

-w, –width WIDTH

Set the window width in pixels.

-h, –height HEIGHT

Set the window height in pixels.

-h, –help

Print usage information and exit