04.RemoteDebugging

Table of contents

• Overview
• Steps
  • 4.1. Introduce debugging support
    • 4.1.1. Technologies
    • 4.1.2. Internal representation
    • 4.1.3. Usage
  • 4.2. Debug camera
    • 4.2.1. Install camera manipulator
    • 4.2.2. Create debug page for camera
    • 4.2.3. Retrieve position and rotation
    • 4.2.4. Alter background color
    • 4.2.5. Add camera's debug page to Debugger
• Result

Overview

This example is part of OpenSceneGraph cross-platform examples.

In this example we implement debug-broker's protocol to support remote debugging across platforms.

Note: this example requires 03.HTTPClient example knowledge.

Steps

4.1. Introduce debugging support

Remote debugging assumes application and debug UI are located at different machines. The most widespread way to communicate between remote machines nowadays is to use HTTP(s) over TCP/IP.

We use debug-broker's protocol to implement remote debugging. debug-broker is a mediator between debugged application (this example) and debug UI (source of user input).

4.1.1. Technologies

debug-broker has the following concepts:

• Debugger
  • is a container of so-called debug pages
  • usually represents a single application
  • requires client code to call its process() function regularly to perform requests
• Page
  • is a container of so-called debug items
  • usually represents a set of related items, e.g., Camera properties
• Item
  • contains alterable entries
  • usually represents properties, e.g., BackgroundColor item for Camera page
  • can be read-only or read-write

debug-broker accepts and replies in JSON format. We use NLohmann's JSON to parse incoming JSON. Outgoing JSON is currently composed manually.

Note: clone NLohmann's JSON alongside OpenSceneGraph cross-platfrom examples' repository.

4.1.2. Internal representation

debug-broker concepts are mapped to the following classes:

• Debugger
  • is a container for Pages
  • uses HTTPClient instance to communicate with debug-broker
  • makes new request
    • each second
    • only after previous request has been completed
• Page
  • is a container for Page::Items
• Page::Item
  • is an entry with alterable value

4.1.3. Usage

Client code:

• creates Debugger instance (source code):

  this->debugger = new debug::Debugger(this->httpClient, name);
  

• provides debug-broker's address (source code):

  this->debugger->setBrokerURL("http://localhost:7999");
  

• regularly calls Debugger's process() function (source code):

  this->debugger->process();
  

4.2. Debug camera

Now that we covered prerequisites, it's time to debug.

Let's debug camera:

• alter background color
• retrieve camera's position and rotation

4.2.1. Install camera manipulator

We can only get camera's position from camera manipulator. Install one (source code):

this->cameraManip = new osgGA::TrackballManipulator;
this->viewer->setCameraManipulator(this->cameraManip);

4.2.2. Create debug page for camera

Create debug page to collect camera related items (source code):

- - - -
debug::Page debugPage;
- - - -
this->debugPage.title = "camera";
- - - -

4.2.3. Retrieve position and rotation

To retrieve camera's position and rotation, we need to register Postion/Rotation item with getter (source code):

this->debugPage.addItem(
    "Position/Rotation",
    // Getter.
    [&] {
        - - - -
        return
            format::printfString(
                "%f,%f,%f/%f,%f,%f",
                pos.x(), pos.y(), pos.z(),
                rot.x(), rot.y(), rot.z()
            );
    }
);

4.2.4. Alter background color

To alter background (camera) color, we need to register BGColor item with both getter and setter (source code):

this->debugPage.addItem(
    "BGColor",
    // Getter.
    [&] {
        - - - -
        return format::printfString("%d,%d,%d", r, g, b);
    },
    // Setter.
    [&](const std::string &value) {
        - - - -
        this->camera()->setClearColor(color);
    }
);

4.2.5. Add camera's debug page to Debugger

Finally, add camera's debug page to Debugger (source code):

this->debugger->addPage(this->debugPage);

Result

Here's a web build of the example.

Now open debug UI and change background color to 255,0,0.