osgverse

Imported from xarray/osgverse (AGENTS.md). Install upstream with npx skills add xarray/osgverse. Copyright stays with the author.

osgVerse - AI Coding Agent Guide

Project Overview

osgVerse is a complete 3D engine solution based on OpenSceneGraph (OSG). It provides a modern rendering pipeline with PBR (Physically Based Rendering), deferred shading, real-time shadows, and comprehensive 3D functionality including physics, animation, and UI systems.

• Language: C++ (C++14/C++17)
• Build System: CMake 3.10+
• License: See LICENSE file

Technology Stack

Core Technologies

• Graphics API: OpenGL 2.0+, OpenGL 3.3+ Core Profile, GLES2/GLES3, WebGL 1/2
• 3D Framework: (Minimum) OpenSceneGraph 3.1.1; (Preferred) OpenSceneGraph 3.6.5
• Build System: CMake 3.10+
• Platforms: Windows (10-11), Linux (Ubuntu/Debian/Kylin/UOS), macOS, Android, WebAssembly (Emscripten)

Key Dependencies

• OpenSceneGraph (Required): Core 3D framework
• OpenGL/GLES: Graphics rendering
• SDL2: Windowing for Android/IOS/WASM
• CUDA/MUSA (Optional): GPU compute
• Bullet3 (Optional): Physics simulation
• Qt5/Qt6 (Optional): Qt-based applications
• FFmpeg (Optional): Video decoding/encoding
• Draco (Optional): Mesh compression
• libIGL (Optional): Geometry processing
• ZLMediaKit (Optional): Media streaming

Embedded 3rdparty Libraries (3rdparty/)

The project includes many embedded third-party libraries:

• blend2d: 2D vector graphics engine
• imgui: Immediate mode GUI (with extensions like ImGuizmo, implot)
• leveldb: Key-value storage
• libhv: High-performance network library
• ktx: Khronos texture format
• ozz: Animation runtime
• recastnavigation: Navigation mesh
• marl: Task scheduler
• meshoptimizer: Mesh optimization
• Eigen: Linear algebra
• And many more (see THIRDPARTY_LICENSES.md for complete list)

Project Structure

osgVerse/
├── CMakeLists.txt              # Root CMake configuration
├── Setup.sh / Setup.bat        # Automated build scripts
├── VerseCommon.h               # Main unified header
├── CODE_STYLE.md               # Coding style guidelines
│
├── 3rdparty/                   # Embedded third-party libraries
│   ├── blend2d/               # 2D graphics
│   ├── imgui/                 # GUI library
│   ├── leveldb/               # Database
│   ├── libhv/                 # Network library
│   ├── ktx/                   # Texture format
│   ├── ozz/                   # Animation
│   └── ...                    # Many more
│
├── pipeline/                   # Rendering pipeline (osgVersePipeline)
│   ├── Pipeline.h/cpp         # Core pipeline
│   ├── DeferredCallback.h/cpp # Deferred shading
│   ├── ShadowModule.h/cpp     # Shadow rendering
│   ├── LightModule.h/cpp      # Lighting system
│   ├── ShaderLibrary.h/cpp    # Shader management
│   └── ...
│
├── modeling/                   # Geometry processing (osgVerseModeling)
│   ├── MeshDeformer.h/cpp     # Mesh deformation
│   ├── GeometryMerger.h/cpp   # Geometry merging
│   ├── Math.h/cpp             # Math utilities
│   └── ...
│
├── readerwriter/              # I/O utilities (osgVerseReaderWriter)
│   ├── DracoProcessor.h/cpp   # Draco compression
│   ├── KTXProcessor.h/cpp     # KTX textures
│   ├── GLTFReader.h/cpp       # GLTF support
│   └── ...
│
├── animation/                  # Animation & physics (osgVerseAnimation)
│   ├── PhysicsEngine.h/cpp    # Bullet physics
│   ├── PlayerAnimation.h/cpp  # Character animation
│   ├── TweenAnimation.h/cpp   # Tweening
│   └── ...
│
├── ui/                         # User interface (osgVerseUI)
│   ├── imgui/                 # ImGui integration
│   ├── Canvas2D.h/cpp         # 2D canvas
│   └── ...
│
├── script/                     # Scripting (osgVerseScript)
│   └── ...
│
├── ai/                         # AI & navigation (osgVerseAI)
│   └── ...
│
├── wrappers/                   # Serialization wrappers (osgVerseWrappers)
│   └── ...
│
├── plugins/                    # OSG plugins
│   ├── osgdb_fbx/             # FBX format
│   ├── osgdb_gltf/            # GLTF format
│   ├── osgdb_ktx/             # KTX format
│   ├── osgdb_3dgs/            # 3D Gaussian Splatting
│   ├── osgdb_ffmpeg/          # Video support
│   └── ...
│
├── tests/                      # Test applications
│   ├── pipeline_test.cpp      # Pipeline testing
│   ├── shadow_test.cpp        # Shadow testing
│   ├── physics_basic_test.cpp # Physics testing
│   └── ...
│
├── applications/               # Main applications
│   ├── viewer/                # Basic viewer
│   ├── viewer_composite/      # Multi-view viewer
│   ├── scene_editor/          # Scene editor
│   ├── earth_explorer/        # Earth visualization
│   ├── qt_viewer/             # Qt integration
│   └── ...
│
├── wasm/                       # WebAssembly specific code
├── android/                    # Android specific code
├── helpers/                    # Build helpers
│   ├── toolchain_builder/     # 3rdparty build tools
│   └── osg_builder/           # OSG build helpers
│
├── assets/                     # Assets (models, shaders, textures)
│   ├── models/                # 3D models
│   ├── shaders/               # GLSL shaders
│   ├── skyboxes/              # HDR skyboxes
│   └── textures/              # Textures
│
├── cmake/                      # CMake modules
│   ├── VerseMacros.cmake      # Build macros
│   └── ...
│
└── build/                      # Build output (generated)

Module Dependency Chain

Build Instructions

Quick Build (Recommended)

Use the provided setup scripts. The first argument selects the build mode (DEFAULT | CORE | GLES2 | GLES3 | WEBGL1 | WEBGL2 | ANDROID); run without arguments to choose interactively. WEBGL1/2 also require the emsdk path as the second argument.

Windows:

Setup.bat DEFAULT       :: Desktop OpenGL -> build/verse_def, install -> build/sdk_def
Setup.bat GLES3         :: OpenGL ES 3   -> build/verse_es,  install -> build/sdk_es
Setup.bat WEBGL2 D:\emsdk   :: WebAssembly  -> build/verse_wasm2, install -> build/sdk_wasm2

Linux/macOS: same modes with ./Setup.sh DEFAULT etc.

The script will:

1. Download OpenSceneGraph if not present
2. Build third-party libraries
3. Build OpenSceneGraph
4. Build osgVerse

Each mode keeps its own build tree under build/, so multiple modes can be built side by side (e.g. verse_def for desktop, verse_wasm2 for web).

Manual Build

# 1. Ensure OpenSceneGraph is built and OSG_ROOT is set
export OSG_ROOT=/path/to/osg

# 2. Create build directory
mkdir build && cd build

# 3. Configure
cmake .. -DOSG_ROOT=$OSG_ROOT

# 4. Build
cmake --build . --target install --config Release

Key CMake Options

Platform-Specific Builds

WebAssembly (Emscripten):

./Setup.sh WEBGL2 /path/to/emsdk

Android:

# Set ANDROID_SDK and ANDROID_NDK environment variables first
export ANDROID_SDK=/path/to/sdk
export ANDROID_NDK=/path/to/ndk
./Setup.sh ANDROID

OpenGL ES:

./Setup.sh GLES3        # or GLES2

Code Style Guidelines

See CODE_STYLE.md for full details. Key points:

Formatting

• 4 spaces indent
• 8 spaces continuation indent
• 100 columns max
• Opening brace { on new line
• Spaces around operators

Naming Conventions

• Constants: UPPER_CASE (e.g., FOO_COUNT)
• Global variables: g_ prefix (e.g., g_globalWarming)
• Static/class variables: s_ prefix
• Private/protected attributes: _ prefix (e.g., _attributeName)
• Class names: UpperCamelCase (e.g., FooBar)
• Methods/variables: lowerCamelCase (e.g., methodName)

File Conventions

• Headers: .h
• Implementation: .cpp
• Inline includes: .inline
• Public headers: #include <module/Header.h>
• Private headers: #include "Header.h"

Example:

class FooBar
{
public:
    void methodName(int arg1, bool arg2);
    int sizeInBytes;
    
private:
    int _attributeName;
    static int s_globalAttribute;
    enum { ONE, TWO, THREE };
};

Testing

Test Organization

Tests are in tests/ directory and categorized as:

Regular Tests (NEW_TEST):

• osgVerse_Test_Compressing - KTX/Draco compression
• osgVerse_Test_Thread - Marl task scheduler
• osgVerse_Test_Volume_Rendering - Volume rendering methods
• osgVerse_Test_Auto_LOD - Geometry merging/optimization
• osgVerse_Test_Sky_Box - Skybox and atmosphere

Examples (NEW_EXAMPLE):

• osgVerse_Test_Pipeline - Basic pipeline usage
• osgVerse_Test_Shadow - Shadow algorithms
• osgVerse_Test_Forward_Pbr - Forward PBR rendering
• osgVerse_Test_ImGui - ImGui integration
• osgVerse_Test_Earth - Earth/atmosphere/ocean
• osgVerse_Test_Physics_Basic - Physics simulation (requires Bullet)
• And many more...

Running Tests

Tests are built when VERSE_BUILD_EXAMPLES=ON (default). In each mode's build tree (e.g. build/verse_def), binaries land in bin/ and are also installed to build/sdk_<mode>/bin. To build and run a single test:

cd build/verse_def                      # or the mode you configured
cmake --build . --target osgVerse_Test_Pipeline --config Release
bin/osgVerse_Test_Pipeline              # Windows: bin\osgVerse_Test_Pipeline.exe

Common usage (see each test's own arguments.read(...) calls for the full list):

bin/osgVerse_Test_Pipeline --screen 1              # select monitor for multi-screen
bin/osgVerse_Test_Pipeline --with-history          # enable history buffer pass
bin/osgVerse_Test_Pipeline --user-module-pre       # add a pre-final-stage UI pass
bin/osgVerse_Test_Pipeline --openxr                # XR rendering

Note: osgVerse_Test_Physics_Basic etc. only build when their optional deps (Bullet/FFmpeg/Draco) are found; missing targets usually mean a dep was not detected, not a build failure.

Development Conventions

Adding a New Library

1. Add source files to appropriate module's CMakeLists.txt
2. Use NEW_LIBRARY() macro for regular libraries
3. Use NEW_CUDA_LIBRARY() for CUDA/MUSA libraries
4. Link dependencies using TARGET_LINK_LIBRARIES()

Adding a New Plugin

1. Create subdirectory in plugins/
2. Create ReaderWriterXXX.cpp implementing OSG plugin interface
3. Add subdirectory to plugins/CMakeLists.txt
4. Use NEW_PLUGIN() macro

Adding a New Test

1. Add .cpp file to tests/
2. Add NEW_TEST(exe_name source.cpp) to tests/CMakeLists.txt
3. Or use NEW_EXAMPLE() for example applications

Export Macros

Use export macros for cross-platform compatibility:

#include <wrappers/Export.h>
// For pipeline: OSGVERSE_PIPELINE_EXPORT
// For modeling: OSGVERSE_MODELING_EXPORT
// etc.

Key Architecture Patterns

Pipeline Architecture

The rendering pipeline uses a stage-based architecture:

• Pipeline: Main orchestrator; owns stages, modules, and framebuffer graph
• Pipeline::Stage: Individual render pass (GBuffer, shadow, forward, final...)
• Modules extend behavior: ShadowModule, LightModule, UserInputModule
• StandardPipelineParameters: config struct passed to Pipeline::setup()

Integration pattern (all examples/tests use it): subclass osgViewer::Viewer, override createRenderer(camera) and return pipeline->createRenderer(camera). Or use osgVerse::StandardPipelineViewer (defined in pipeline/Pipeline.h, implemented in pipeline/PipelineStandard.cpp) for a ready-made viewer. See tests/pipeline_test.cpp and tests/shadow_test.cpp. A Global.h osgVerse::globalInitialize(argc, argv) call must run before creating the viewer.

Shader compatibility layer: shaders must NOT use raw GLSL keywords. Write them with the VERSE_* macros injected by ShaderLibrary::createShaderDefinitions() (see pipeline/ShaderLibrary.cpp): VERSE_MATRIX_MVP, VERSE_TEX1D/2D/3D/CUBE, VERSE_VS_IN/OUT, VERSE_FS_IN, VERSE_FS_FINAL, VERSE_lambertDiffuse, VERSE_blinnPhongSpecular. This keeps one shader source working on OpenGL, GLES and WebGL. Without these macros shaders will fail on ES/WASM.

Static build plugin registration: with VERSE_STATIC_BUILD/OSG_LIBRARY_STATIC, each test/plugin must call USE_OSG_PLUGINS(), USE_VERSE_PLUGINS(), and USE_GRAPICSWINDOW_IMPLEMENTATION(SDL/GLFW) at the top of main() or plugins won't load. See tests/pipeline_test.cpp for the exact #ifdef block.

Serialization Wrappers (wrappers/)

Custom osgVerse classes are serialized through osgDB::ObjectWrapper serializers. Each wrapper is a cpp file in wrappers/ that builds an osgDB::ObjectWrapper using macros like ADD_USER_SERIALIZER, ADD_VECTOR_SERIALIZER, REGISTER_METHOD (see wrappers/Geometry_FixedWrapper.cpp and wrappers/WrapperMethods.cpp). These keep .osg/.osgb scenes with custom node types working with stock osgDB::readNodeFile. updateOsgBinaryWrappers() fixes binary wrappers after loading; it is called by external tools via osgVerse::updateOsgBinaryWrappers(...).

Memory Management

• Uses OSG's reference counting (osg::ref_ptr)
• Custom allocators available via VERSE_USE_MIMALLOC

SIMD Support

Automatic SIMD detection and compilation:

• SSE/SSE2/SSE3/SSSE3/SSE4.1/SSE4.2
• AVX/AVX2/AVX512
• Automatic flags applied via VERSE_SIMD_FEATURES

Security Considerations

1. Buffer Overflow: Use OSG's array classes and bounds checking
2. Shader Injection: Validate all shader inputs
3. File I/O: Use OSG's virtual file system for sandboxing
4. Network: libhv includes mbedtls for TLS support

Troubleshooting

Common Build Issues

OpenSceneGraph not found:

• Set OSG_ROOT environment variable or CMake variable
• Or place OSG source at ../OpenSceneGraph

GLES libraries not found:

• For GLES builds, provide path to libEGL.so and libGLESv2.so
• Use Setup.sh <path_to_gles_libs>

CUDA/Compiler incompatibility:

• Check CUDA version against compiler version compatibility
• See CMakeLists.txt line ~353-396 for version checks

Static build issues:

• Enable VERSE_USE_OSG_STATIC to use static OSG
• This forces VERSE_STATIC_BUILD automatically

Platform-Specific Notes

Linux (Kylin/UOS):

• May need VERSE_FIND_LEGACY_OPENGL=ON
• May need VERSE_USE_GLIBCXX11_ABI=OFF for older systems

macOS:

• Uses .so suffix for shared libraries
• May need Google Angle for GLES support

Windows:

• Use Visual Studio 2017-2022 recommended
• MSYS2/MinGW also supported
• PDB files installed with VERSE_INSTALL_PDB_FILES=ON

Resources

• README.md: Full project documentation
• CODE_STYLE.md: Detailed coding standards
• TODO_cn.md: Development roadmap (Chinese)
• THIRDPARTY_LICENSES.md: Third-party license information

Contributing

When contributing:

1. Follow the code style in CODE_STYLE.md
2. Test on multiple platforms if possible
3. Update this file if build processes change
4. Add tests for new features