Integration Phase 1e: Sending Data to the Visual Debugger

Once you have your game set up to accept connections from the Navigation Lab, you can send your own data, shapes and volumes to the Navigation Lab. The Navigation Lab displays your data just like the debugging data sent by the classes native to the Autodesk Navigation. Your data can be recorded, saved to clips, and replayed just like any other data.

You can send debugging data using:

The KY_LOG_MESSAGE macro. Use this approach to send messages to the Log panel in the Navigation Lab (as well as to any other log outputs configured for your BaseSystem).
The methods of the VisualDebugServer class. Use this approach for statistics and data values.
A ScopedDisplayList object. Use this approach for visual data to be rendered in the 3D view of the Navigation Lab.

The code example below creates and sends a display list with a lifespan of a single frame, and repeats the process at each frame. However, if your display list contains data that does not change often, you can instead create it with a user-defined lifespan, and send it once. Its data is then shown at each frame until you either change its data or remove it. For details on this alternative, see Visual Debugging.

The following code example shows all three approaches.

Note that:

Since the visual debugging system is deactivated in the Release build of the Autodesk Navigation libraries, it is generally recommended for best performance that you avoid running visual debugging code when using the Release libraries. For example, you can include the code inside an \#ifndef KY_CONFIG_RELEASE ... #endif block.
It is also recommended that you test that the visual debugging system is ready by calling VisualDebugServer::IsConnected(). This ensures that the visual debug server is set up, a new frame has been started, and a client is connected.

Skipping these recommendations will not cause errors, but does waste the computations involved in creating internal objects that will never actually get sent to the Navigation Lab.

[code from Tutorial_FirstIntegration.cpp]

#include "gwnavruntime/visualsystem/displaylist.h"
...

void MyGameWorld::TestVisualDebugger()
{
// Visual debugging is disabled in Release builds. Even though the symbols and functions are available, they do nothing.
// Guarding this code is not necessary, but is recommended in order to prevent useless computations.
#ifndef KY_CONFIG_RELEASE 
    Kaim::VisualDebugServer* visualDebugServer = m_navWorld->GetVisualDebugServer();

    // always check the state of the VisualDebugServer
    // to avoid costly construction of messages for nothing
    if (visualDebugServer == KY_NULL || visualDebugServer->IsConnected() == false)
        return;

    const char* myCategoryName = "MyGame";

    // Sends a message to the Log window of the Navigation Lab
    static KyUInt32 framecount = 0;
    KY_LOG_MESSAGE(("FrameCount: %d", framecount));
    framecount++;

    // Sends a single data value
    KyUInt32 someKindOfInformation = 1256;
    visualDebugServer->SendUInt32("SomeKindOfInformation", someKindOfInformation, myCategoryName);

    // Sends current, average, max, and min stats computed by the game
    const char* someKindOfStat = "SomeKindOfStat";
    KyFloat32   currentValue   = 2.56f;
    KyFloat32   averageValue   = 2.56f;
    KyFloat32   maxValue       = 3.026f;
    KyFloat32   minValue       = 0.21f;
    visualDebugServer->SendStats(someKindOfStat, currentValue, averageValue, maxValue, minValue, myCategoryName);

    // Visual information is sent using a display list
    Kaim::Vec3f boxLowerCornerPosition = Kaim::Vec3f(-5.0f, -5.0f, 0.0f);
    Kaim::Vec3f boxExtents             = Kaim::Vec3f(3.0f, 2.0f, 1.0f);
    Kaim::Vec3f positionA              = Kaim::Vec3f(0.0f, 2.0f, 0.0f);
    Kaim::Vec3f positionB              = Kaim::Vec3f(10.0f, 10.0f, 0.0f);
    KyFloat32   radius                 = 0.4f;
    KyFloat32   height                 = 2.0f;

    // The Autodesk Navigation coordinate system is Z-up, right-handed,
    // in meters. Always convert positions, vectors and sizes from the coordinate
    // system you use in your game. You can set up a Kaim::CoordSystem object, and use
    // its methods to do the conversions for you, as shown below.
    boxLowerCornerPosition = m_coordSystem.ClientToNavigation_Pos( boxLowerCornerPosition );
    boxExtents             = m_coordSystem.ClientToNavigation_Pos( boxExtents );
    positionA              = m_coordSystem.ClientToNavigation_Pos( positionA );
    positionB              = m_coordSystem.ClientToNavigation_Pos( positionB );
    radius                 = m_coordSystem.ClientToNavigation_Dist( radius );
    height                 = m_coordSystem.ClientToNavigation_Dist( height );
    
    {
        // Create a display list and send a line
        Kaim::ScopedDisplayList displayList(m_navWorld, Kaim::DisplayList_Enable);
        displayList.InitSingleFrameLifespan("Simple Display List", myCategoryName);
        displayList.PushLine(positionB, positionB + Kaim::Vec3f::UnitZ(), Kaim::VisualColor::White);
        // The ScopedDisplayList is automatically sent to the Navigation Lab
        // when it goes out of scope.
    }

    {
        // Create a second display list and send more shapes
        Kaim::ScopedDisplayList displayList(m_navWorld, Kaim::DisplayList_Enable);
        displayList.InitSingleFrameLifespan("Complex Display List", myCategoryName);

        Kaim::ShapeColor shapeColor;
        shapeColor.m_triangleColor = Kaim::VisualColor(255, 255, 0);
        shapeColor.m_lineColor     = Kaim::VisualColor(175, 175, 0);

        displayList.PushVerticalCylinder( positionA, radius, height, 10, shapeColor);
        displayList.PushLine( positionA, positionB, Kaim::VisualColor::Red);

        shapeColor.m_triangleColor = Kaim::VisualColor(0, 255, 0, 128);
        shapeColor.m_lineColor     = Kaim::VisualColor(0, 128, 0, 255);

        Kaim::Box3f someBox(boxLowerCornerPosition, boxLowerCornerPosition + boxExtents);
        displayList.PushBox(someBox, shapeColor);

        displayList.PushText( positionB + Kaim::Vec3f::UnitZ(), Kaim::VisualColor(0, 255, 255), "Some text");
        // Again, the ScopedDisplayList is automatically sent to the Navigation Lab
        // when it goes out of scope.
    }
#endif
}

When you connect the Navigation Lab to your game, you should now see:

Your log messages, listed in the Log panel:
Your data and statistics, shown in the Profiling panel:
Your visual lines and shapes, shown in the 3D view:

You can also show and hide the data sent in your display lists in the Visual debug panel. The category name you specified for your display lists is shown at the bottom of the panel, under the heading Display lists. If you expand this category, you can show and hide the individual display lists.

Integration Phase 1e: Sending Data to the Visual Debugger

Parent topic