Build a native OVGL stage viewer#
Build a C++ application that loads a stage through Foundation’s OVStage adapter and renders it with the OVGL debug viewport. Compare this stage-viewer workflow with a Python application that owns both simulation and rendering.
Learning objectives#
After completing this tutorial, you can:
Author viewport inputs through the Foundation C++ API.
Configure an OVGL viewport and write interactive camera poses to the in-memory stage.
Load a local or remote stage without overriding its units or up axis.
Choose between a general stage viewer and a coupled simulation viewport.
Prerequisites#
Complete Install and run.
Install a C++ toolchain and the Foundation and OVGL native SDK components.
Use a graphical desktop for interactive runs. On Linux, provide an accessible X11 display and a compatible EGL/OpenGL implementation.
Run the commands in this tutorial from the repository root.
Examples used#
Example |
Role in this tutorial |
|---|---|
Implements the C++ application loop, stage loading, and OVGL viewport. |
|
Publishes simulated transforms for viewing through a Python OVGL viewport. |
Each example page lists its source directory, requirements, and runner commands.
Choose an integration model#
Use the native viewer to inspect a procedural scene, local stage file, or supported asset URL. Use a coupled simulation and viewport loop when the same application must produce and display changing state.
Model |
Stage ownership |
Update responsibility |
|---|---|---|
Native stage viewer |
Loads or composes a stage for inspection. |
OVGL handles navigation and rendering; the application writes camera poses. |
Coupled simulation viewport |
Owns the physics stage and viewport together. |
The application steps physics and publishes transforms before rendering. |
Build and run the viewer#
Build and open the procedural cube scene:
source/examples/example.sh build ovgl_viewport.cpp
source/examples/example.sh run ovgl_viewport.cpp
.\source\examples\example.bat build ovgl_viewport.cpp
.\source\examples\example.bat run ovgl_viewport.cpp
Pass one local path or supported asset URL to inspect another stage:
source/examples/example.sh run ovgl_viewport.cpp -- /path/to/stage.usd
.\source\examples\example.bat run ovgl_viewport.cpp -- C:/path/to/stage.usd
Drag with the left mouse button to look around, scroll the mouse wheel to dolly, and use W, A, S, D, Q, and E to move. Hold Shift to move faster, press R to reset the camera, press H to toggle the debug HUD, and press Escape to close the viewport.
Create and render the viewport#
ViewportConfiguration identifies the render product, window dimensions,
frame limit, and visibility. The camera callback writes navigation changes
through Foundation’s Camera wrapper:
viewport::ViewportConfiguration viewportConfiguration;
viewportConfiguration.title = "Isaac Sim OVStage + OVGL Viewport";
viewportConfiguration.width = g_kInitialWidth;
viewportConfiguration.height = g_kInitialHeight;
viewportConfiguration.maximumFrames = commandLine.maximumFrames;
viewportConfiguration.visible = !commandLine.headless;
viewportConfiguration.renderProductPath = g_kRenderProductPath;
void* nativeStage = stage.getStagePtr();
if (!nativeStage)
{
throw std::runtime_error("Foundation did not retain a native stage for the loaded scene");
}
const viewport::CameraPoseWriter cameraPoseWriter = [&camera](const viewport::CameraPose& pose)
{
array::Array positions(
std::vector<std::vector<double>>{ { pose.position[0], pose.position[1], pose.position[2] } });
array::Array orientations(std::vector<std::vector<double>>{
{ pose.orientation[0], pose.orientation[1], pose.orientation[2], pose.orientation[3] } });
camera.setWorldPoses(positions, orientations);
};
viewport::Viewport viewer(static_cast<ovstage_instance_t*>(nativeStage), cameraPoseWriter, viewportConfiguration);
uint64_t renderedFrames = 0;
while (viewer.pollEvents())
{
renderedFrames = viewer.render().frameNumber;
}
std::cout << "Viewport rendered " << renderedFrames << " frame(s)." << std::endl;
Create, use, and destroy the viewport on the application main thread. The render loop continues until the window closes or the configured frame limit is reached.
In the coupled Python workflow, the application publishes the physics result before asking the viewport to render the next frame:
if step_count:
completed_steps = physics_manager.step(steps=step_count)
simulation_step += completed_steps
accumulated_simulation_time -= completed_steps * _PHYSICS_DT
if not physics_manager.publish_transforms_to_stage():
raise RuntimeError("Physics transform publication failed.")
positions, _ = simulated_cube.get_world_poses()
final_height = float(positions.numpy()[0, 2])
frame = viewport.render()
This explicit publication is unnecessary for a static stage viewer, but it is required when an external simulation backend changes transforms that OVGL must observe.
Verify both rendering paths#
Run both examples without a visible window:
source/examples/example.sh test ovgl_viewport.cpp:headless
source/examples/example.sh test falling_cube.visualize_simulation:headless
.\source\examples\example.bat test ovgl_viewport.cpp:headless
.\source\examples\example.bat test falling_cube.visualize_simulation:headless
The native test renders one frame and reports its frame count. The Python
test.py verifies that the cube moves and that the renderer produces changed
frame data after transform publication.
Tradeoffs#
Use the native viewer when stage inspection is the application boundary. Use the coupled loop when your application owns simulation timing and must display each published state.
Next steps#
Continue with Control differential-drive and holonomic-drive robots to apply the coupled simulation and viewport pattern to mobile robots.