ramses-logic-viewer

Synopsis

ramses-logic-viewer [options] <ramsesfile> [<logicfile> <luafile>]

Description

ramses-logic-viewer is a tool which can load, configure and display Ramses (<ramsesfile>) and Ramses Logic (<logicfile>) binary files alongside with a custom configuration (<luafile>). It also provides a GUI to inspect the displayed scene.

  • Both <ramsesfile> and <logicfile> are typically created by the Ramses Composer.

  • <luafile> is an optional configuration file written in lua to modify the scene view (see Lua configuration API for details)

  • Both <logicfile> and <luafile> are found in the same path as <ramsesfile> if not provided as arguments. For auto-detection the file extensions rlogic and lua are expected.

  • If no <luafile> is found, the viewer will show the scene and propose to store a default configuration.

  • Display size is auto-detected based on the first camera viewport found in the scene. This can be overridden by the options ramses-logic-viewer -w and ramses-logic-viewer -h.

The tool’s intended use-cases are primarily:

  • Inspect binary files (as a simplified version of the Ramses Composer, or for platforms where the Ramses Composer is not available)

  • Demonstrate or test scene behavior for different input values

  • Make screenshots of scenes (e.g. to perform automated image-based tests in build jobs)

Options

--no-offscreen

Renders the scene directly to the window’s framebuffer. Screenshot size will be the current window size. If switched off (default), the scene is rendered to an offscreen buffer with the initial scene size.

--exec=<luafunction>

Calls the given <luafunction> defined in <luafile> and exits. This can be e.g. used to run a test case and/or to make a screenshot

-w WIDTH

overrides the auto-detected display width

-h HEIGHT

overrides the auto-detected display height

Lua configuration API

The ramses-logic-viewer exposes a lua module rlogic that allows to interact with the viewer’s logic engine instance. rlogic mimics the Ramses Logic C++ API and provides some extra interfaces to take screenshots and define interactive views.

Logic Nodes

The module rlogic provides members to access all Logic Node types:

The Logic Node instances can be either found by name or iterated.

Example:

-- returns the LuaScript node with the name `foo` or nil if it does not exist
rlogic.scripts.foo

-- iterates through all LuaScript instances
for script in rlogic.scripts() do
    print(script)
end

Logic Properties

Logic Nodes own Logic Properties. They are accessed like this:

  • struct property children are indexed by name

  • array property children are indexed by number (first element has index 1 by lua convention)

  • property values are indexed by the value attribute

Example:

rlogic.scripts.foo.IN.integerProperty.value = 6
rlogic.scripts.foo.IN.stringProperty.value = "Hello World"
rlogic.scripts.foo.IN.structProperty.vec3iChild.value = { 42, 44, 0 }
rlogic.scripts.foo.IN.arrayProperty[1].integerChild.value = 5

-- returns the property's value
rlogic.scripts.foo.IN.integerProperty.value
-- returns the property object
rlogic.scripts.foo.IN.integerProperty

Note

Properties can be readonly if they are output properties or linked to an output property. Trying to set values to them will cause a runtime error.

Views

rlogic.views can be used to demonstrate typical scene configurations to the user. If the lua script defines views, the user can simply switch between them in the UI and does not need to know how to configure all the corresponding properties.

A view is a lua table that contains the following members:

name

A string attribute that contains the view’s name

update(time_ms)

A function that is called for every frame by the ramses-logic-viewer. The time_ms parameter is a monotonic time value in milliseconds.

description

An optional string attribute that may contain a longer text to describe the view.

inputs

An optional array of writable (input) properties. The user will see a dedicated UI to modify these properties.

Example:

simpleView = {
    name = "Simple View",
    update = function(time_ms)
        scripts.foo.color.value = 1
    end
}

animatedView = {
    name = "Animated View",
    description = "Scene animates based on the input time value",
    update = function(time_ms)
        scripts.foo.time.value = time_ms
    end
}

interactiveView = {
    name = "Interactive View",
    description = "Scene animates based on the input time value. User can modify the color by UI",
    update = function(time_ms)
        scripts.foo.time.value = time_ms
        -- description could optionally be updated based on the current state:
        -- interactiveView.description = "..."
    end,
    inputs = { scripts.foo.color }
}

-- assigns the view list
rlogic.views = {simpleView, animatedView, interactiveView}

Screenshots

Screenshots can be taken by the rlogic.screenshot(filename) function. The ramses-logic-viewer will implicitly update the logic state before.

rlogic.scripts.foo.IN.color.value = "red"
rlogic.screenshot(foo_red.png)
rlogic.scripts.foo.IN.color.value = "green"
rlogic.screenshot(foo_green.png)

Note

By default the Logic Viewer creates an offscreen buffer for the scene. That’s why the screenshot’s size is independent of the window size and does not contain the Logic Viewer’s UI.

Logic Engine Update

The logic engine is automatically updated (rlogic::LogicEngine::update()) before a new frame is drawn or before a screenshot is stored. In batch mode (ramses-logic-viewer --exec) it’s sometimes useful to explicitly update the logic engine state by calling rlogic.update():

rlogic.scripts.foo.IN.color.value = "red"
rlogic.update()
if not rlogic.scripts.foo.OUT.color.value == {255, 0, 0} then
    error("unexpected value")
end