Imported from xarray/osgverse (
AGENTS.md). Install upstream withnpx 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
| Module | Dependencies | Optional External |
|---|---|---|
| osgVerseDependency | - | - |
| osgVerseModeling | Dependency | libIGL |
| osgVersePipeline | Dependency, Modeling | CUDA |
| osgVerseScript | Dependency, Pipeline | - |
| osgVerseAI | Dependency, Modeling | - |
| osgVerseAnimation | Dependency, Pipeline, Modeling | Bullet, Effekseer |
| osgVerseUI | Dependency, Modeling, Script | libCEF |
| osgVerseReaderWriter | Dependency, Animation, Modeling, Pipeline | libDraco, SDL |
| osgVerseWrappers | ALL | - |
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:
- Download OpenSceneGraph if not present
- Build third-party libraries
- Build OpenSceneGraph
- 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
| Option | Type | Default | Description |
|---|---|---|---|
OSG_ROOT |
Path | - | OpenSceneGraph root directory |
VERSE_3RDPARTY_PATH |
Path | ../Dependencies | Third-party libraries path |
VERSE_BUILD_EXAMPLES |
Bool | ON | Build examples and tests |
VERSE_BUILD_WITH_QT |
Bool | ON | Build Qt-based applications |
VERSE_BUILD_WITH_CUDA |
Bool | ON | Build CUDA-based libraries |
VERSE_STATIC_BUILD |
Bool | OFF | Static library build |
VERSE_USE_OSG_STATIC |
Bool | OFF | Use static OSG |
VERSE_SUPPORT_CPP17 |
Bool | ON | Enable C++17 features |
VERSE_BUILD_DEPRECATED_TESTS |
Bool | OFF | Build deprecated tests |
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 compressionosgVerse_Test_Thread- Marl task schedulerosgVerse_Test_Volume_Rendering- Volume rendering methodsosgVerse_Test_Auto_LOD- Geometry merging/optimizationosgVerse_Test_Sky_Box- Skybox and atmosphere
Examples (NEW_EXAMPLE):
osgVerse_Test_Pipeline- Basic pipeline usageosgVerse_Test_Shadow- Shadow algorithmsosgVerse_Test_Forward_Pbr- Forward PBR renderingosgVerse_Test_ImGui- ImGui integrationosgVerse_Test_Earth- Earth/atmosphere/oceanosgVerse_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
- Add source files to appropriate module's
CMakeLists.txt - Use
NEW_LIBRARY()macro for regular libraries - Use
NEW_CUDA_LIBRARY()for CUDA/MUSA libraries - Link dependencies using
TARGET_LINK_LIBRARIES()
Adding a New Plugin
- Create subdirectory in
plugins/ - Create
ReaderWriterXXX.cppimplementing OSG plugin interface - Add subdirectory to
plugins/CMakeLists.txt - Use
NEW_PLUGIN()macro
Adding a New Test
- Add
.cppfile totests/ - Add
NEW_TEST(exe_name source.cpp)totests/CMakeLists.txt - 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 graphPipeline::Stage: Individual render pass (GBuffer, shadow, forward, final...)- Modules extend behavior:
ShadowModule,LightModule,UserInputModule StandardPipelineParameters: config struct passed toPipeline::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
- Buffer Overflow: Use OSG's array classes and bounds checking
- Shader Injection: Validate all shader inputs
- File I/O: Use OSG's virtual file system for sandboxing
- Network: libhv includes mbedtls for TLS support
Troubleshooting
Common Build Issues
OpenSceneGraph not found:
- Set
OSG_ROOTenvironment 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_STATICto use static OSG - This forces
VERSE_STATIC_BUILDautomatically
Platform-Specific Notes
Linux (Kylin/UOS):
- May need
VERSE_FIND_LEGACY_OPENGL=ON - May need
VERSE_USE_GLIBCXX11_ABI=OFFfor older systems
macOS:
- Uses
.sosuffix 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:
- Follow the code style in
CODE_STYLE.md - Test on multiple platforms if possible
- Update this file if build processes change
- Add tests for new features
