Skip to content
/ osgverse Public

osgVerse, a complete 3d engine solution based on OpenSceneGraph.

License

MIT license
162 stars 33 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

xarray/osgverse

BranchesTags

Repository files navigation

Image

osgVerse

Introduction

osgVerse, a complete 3D engine solution based on OpenSceneGraph.

Operating System Compiler Supported Notes
Windows 11 Visual Studio 2017-2022 ✔️
Windows 10 Visual Studio 2017-2022 ✔️
Windows 10 Visual Studio 2015 ✔️ Requires VS2015 Update-3
Windows 10 MSYS2 (GCC 10.2) ✔️
Windows 10 Intel Compiler 2023 ✔️ cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icx -GNinja ..
Windows 10 UWP 🔜
Ubuntu 18.04 GCC 7.5 (or later) ✔️
Debian 11.7.0 GCC 10.2 (or later) ✔️
Kylin v10 GCC 8.3 (or later) ✔️ Set VERSE_FIND_LEGACY_OPENGL to ON
NeoKylin v7 GCC 8.5 (built manually) ✔️ Must disable VERSE_USE_GLIBCXX11_ABI
Mac OS X 🔜
Android WSL + NDK r20e (Clang) ✔️
IOS 🔜
WebAssmebly WSL + Emscripten 3.1.64 ✔️ Supports GLES2 (WebGL1) and GLES3 (WebGL2)

Main Features (ongoing to v1.0)

  • Supports from OSG 3.1.1 to the latest version, and GLSL 1.2 to 4.6, so to work with most hardware in the world.
  • (PARTLY) Supports PBR-based rendering and deferred pipeline, with real-time shadowing and deferred lighting.
  • (PARTLY) Supports physics simuation based on Bullet3/PhysX library, and character animation based on OZZ library.
  • Supports complex model simplication, optimizing and tiling, and saving to OSGB format for better efficiency.
  • Provides a LevelDB nosql plugin, for reading tiles from database rather than local folders.
  • Provides a media streaming plugin, which supports pixel streaming through WebRTC / Websockets.
  • Provides a scripting plugin, which supports scripting using OSGB serialization and changing to Restful-like format.
  • Supports GL3 Core profile, as well as GLES2 / GLES3. Google Angel is also supported for future bridging uses.
  • (PARTLY) Supports major desktop and mobile operating systems, including Windows, Linux, Mac OSX, Android and IOS.
  • Supports major embedded devices with GPU supports, including ARM and RISC-V.
  • Supports Emscripten / WASM compilation and works with WebGL 1/2 based browsers.
  • Provides an initial visual scene editing tool, comparing with the famous Unity Editor.

Screenshots

  • osgVerse_Viewer: PBR and deferred pipeline with Desktop GL Image
  • osgVerse_ViewerWASM: PBR and deferred pipeline with WebGL 1.0, compiled from WASM Image
  • osgVerse_JsCallerWASM: Scriptable osgb rendering with WebGL 1.0, compiled from WASM Image

Dependencies

  1. Please use CMake 3.0 or higher version. (https://cmake.org/download/)
  2. Please use a C++ compiler supporting C++ 14 at least.
  3. OpenSceneGraph is always required for building osgVerse. (https://github.com/openscenegraph/OpenSceneGraph) Current project mainly depends on OSG 3.7.0, but can compile on OSG 3.1.1 or later versions.
  4. Important dependencies:
  1. Optional dependencies:

Supported Hardware

To use osgVerse libraries and applications, OpenGL version must be higher than 2.0. Both core profile and compatible profile will work. Our project uses the GLSL functionality, and supports from GLSL 120 to the latest GLSL version. Our project is already tested on graphics cards listed as below:

Graphics Card OpenGL Version Supported Notes
NVIDIA RTX 30** Series 4.6 / GLSL 4.6 ✔️
NVIDIA 10** Series 4.6 / GLSL 4.6 ✔️
NVIDIA 1070 (Nouveau) 4.3 / GLSL 4.3 ⚡ Display has broken problems with Nouveau driver
NVIDIA GT720 4.6 / GLSL 4.6 ✔️ Current frame rate < 12fps
NVIDIA Quadro K2200 4.6 / GLSL 4.6 ✔️
AMD Radeon RX5500 🔜
AMD Radeon (TM) Graphics 4.6 / GLSL 4.6 ✔️ Current frame rate < 15fps
Intel UHD Graphics 4.6 / GLSL 4.6 ✔️ Current frame rate ~= 30fps
MooreThreads S80, S2000 3.3 / GLSL 3.3 ✔️ Enable VERSE_USE_MTT_DRIVER before solving driver problems
PhytiumVR AXT-16-512 3.0 / GLSL 3.3 ✔️ Current frame rate < 10fps. Will go blank if GLSL code has '#include'... Why?
JingJia Micro JM7201 🔜
Zhaoxin C-960 (SIS) 3.2 / GLSL 1.5 ⚡ Segment fault in osg::Texture at present
VirtualBox SVGA 3D 2.1 / GLSL 1.2 ⚡ osgVerse_Test_Pipeline can work; standard can't

Modules

  1. osgVersePipeline: modern rendering pipeline supporting PBR materials, realtime shadows, deferred lighting and effects.
  2. osgVerseReaderWriter: full featured reader-writer support for FBX, GLTF and KTX formats, and for more later.
  3. osgVerseAnimation: physics and character animation supports.
  4. osgVerseModeling: model simplification pipeline, modeling operators, and computational geometry utilities
  5. osgVerseUI: IMGUI based quick UI support, HTML based UI solution, and related utilities.
  6. osgVerseScript: Scripting support based on OSG serialization functionalities.
  7. osgVerseAI: Artificial-Intelligence related classes, including navigation-mesh and so on.
  8. TBD...

Applications

  1. osgVerse_SceneEditor: a forward-looking scene editor for osgVerse scene & components.
  2. osgVerse_Viewer: a single-camera viewer with modern rendering pipeline support.
  3. osgVerse_ViewerComposite: a multi-camera (multi-view) viewer with modern rendering pipeline support.
  4. osgVerse_ViewerGLES: an example demostrating how to integrate osgVerse with SDL2, mainly with GLES2/3.
  5. osgVerse_EarthViewer: an example demostrating how to integrate osgVerse with osgEarth.
  6. osgVerse_QtViewer: an example demostrating how to integrate osgVerse with Qt.
  7. osgVerse_ViewerWASM (wasm/pbr_demo): an example of WASM, with modern rendering pipeline support.
  8. osgVerse_JsCallerWASM (wasm/script_demo): an example of WASM, demostrating how to use OSGB scripts with JS.
  9. TBD...

Tests and Examples

  1. osgVerse_Test_ImGui: a quick test for demostrating the use of IMGUI in osg scene.
  2. osgVerse_Test_Mesh_Process: a mesh process and topology builder example.
  3. osgVerse_Test_Physics_Basic: a physics world example supporting rigid bodies & kinematics, requiring Bullet3.
  4. osgVerse_Test_Shadow: a test for shadow algorithm debugging and optimizing.
  5. osgVerse_Test_Pipeline: a program for simple cases and compatiblity tests of osgVerse pipeline.
  6. osgVerse_Test_Pbr_Prerequisite: a quick utility to pre-compute global PBR textures and save them to IBL osgb files.
  7. osgVerse_Test_Paging_Lod: a test for paged LOD file combination, optimization and transferring to levelDB.
  8. osgVerse_Test_Point_Cloud: a test for point cloud viewing and manipulating.
  9. osgVerse_Test_Media_Stream: a test for media streaming / pixel streaming, including server and pusher implementation.
  10. osgVerse_Test_Restful_Server: a test for restful HTTP API, which is based on libhv.
  11. osgVerse_Test_Scripting: a test for scripting implementation based on OSGB serialization format.
  12. osgVerse_Test_Compressing: a test for KTX texture compression (DXT / ETC) and Draco geometry compressing.
  13. osgVerse_Test_Thread: a test for using the Marl thread task scheduler along with osgViewer.
  14. osgVerse_Test_Volume_Rendering: a test for different methods to implement volume rendering.
  15. osgVerse_Test_Symbols: a test for displaying massive symbols with icons and texts.
  16. osgVerse_Test_Tween_Animation: a test for tween animations, like path and data-driven animations.
  17. Deprecated tests:
  • osgVerse_Test_FastRtt: a quick test for using newly-introduced RTT draw callback.
  • osgVerse_Test_Obb_KDop: a quick test for creating a model's obb/kdop bounding volume.
  • osgVerse_Test_CubeRtt: a quick test for render-to-cubemap (6 faces) demonstaration.
  • osgVerse_Test_Indirect_Draw: a demo program to demonstrate how to use indirect drawing of OpenGL 4.x.
  • osgVerse_Test_Tesselation: a demo program to demonstrate how to use tessellation shaders of OpenGL 4.x.
  • osgVerse_Test_MultiView_Shader: a test for using geometry shader to implement multi-view rendering.

OSG-style Plugins

  1. osgdb_verse_ept: a plugin for massive point cloud paging and rendering based on Entwine.
  2. osgdb_verse_fbx: a plugin with full-featured FBX format support.
  3. osgdb_verse_gltf: a plugin with full-featured GLTF & GLB format support.
  4. osgdb_verse_web: a plugin for HTTP and more web protocols, which may replace the curl plugin.
  5. osgdb_verse_image: a plugin for reading common image formats like JPEG and PNG. It mainly works for WASM case.
  6. osgdb_verse_webp: a plugin for reading WEBP formats. It mainly works for 3dtiles scene.
  7. osgdb_verse_leveldb: a plugin for reading/writing from LevelDB database.
  8. osgdb_verse_ms: a plugin for reading/writing from media streaming protocols like RTSP/RTMP/WebRTC.
  9. osgdb_vese_tiles: a plugin for reading Cesium 3dtiles (.json) and Osgb files (metadata.xml, or just the root folder).
  10. osgdb_pbrlayout: a pseudo-plugin to change PBR textures' layout to osgVerse standard. It supports following options:
  • Diffuse (D), Specular (S), Normal (N), Metallic (M), Roughness (R), Occlusion (O), Emissive (E), Ambient (A), Omitted (X)
  • Every source texture is defined by a option character and a channel number (1-4), and separated with a ','.
  • Example input: model.fbx.D4,M1R1X2,N3.pbrlayout (Tex0 = Diffuse x 4, Tex1 = Metallic+Roughness, Tex2 = Normal)
  • All layouts will be converted to osgVerse standard: D4,N3,S4,O1R1M1,A3,E3
  1. TBD...

Assets

  1. models: 3D models for test use, mainly in GLTF format.
  2. shaders: Shaders for osgVerse rendering pipeline use.
  3. skyboxes: Skyboxes for test use, may be one HDR image or 6 cubemaps.
  4. misc: Chinese IME CiKu files, font files, screenshots...
  5. tests: Some test data

Prepare and build third-party libraries

  1. By default, osgVerse will find third-party libraries as follows:
  • OpenGL: from the system. Note that some Linux distributions (e.g., Qilin) should enable VERSE_FIND_LEGACY_OPENGL first.
  • OpenSceneGraph: from environment variable $OSG_ROOT.
  • SDL, Draco, Bullet, etc.: from CMake variable ${VERSE_3RDPARTY_PATH}, which is <osgverse_folder>/../Dependencies by default.
    • Actually path to find includes and libraries will be automatically set to '${VERSE_3RDPARTY_PATH}/'.
    • For x86/x64 build: is 'x86/x64'.
    • For Android build: is 'android'.
    • For MacOSX/IOS build: is 'apple/ios'.
    • For WebAssembly (WASM) build: is 'wasm'.
    • For Windows UWP build: is 'uwp'.
  1. Build Draco:
  • For WebAssembly (WASM):
    • export EMSCRIPTEN=<emsdk_folder>/upstream/emscripten
    • cmake -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake -DDRACO_WASM=ON -DDRACO_JS_GLUE=OFF -DCMAKE_INSTALL_PREFIX=<your_path>/Dependencies/wasm <draco_folder>
  • See https://github.com/google/draco/blob/master/BUILDING.md for other platforms.
  1. Build ZLMediaKit: TBD...
  2. TBD...

Build from Source

  1. Assume that osgVerse source code is already at <osgverse_folder>.
  2. Desktop Windows / Linux
  • Make sure you have a compiler environment (e.g., Visual Studio).
  • Download and install CMake tool.
  • Download OSG prebuilt libraries or build them from source, extracting to <osg_sdk_folder>.
  • Declare an environment variable OSG_ROOT, to indicate OSG root directory:
    • (Windows) $ set OSG_ROOT=<osg_sdk_folder>
    • (Linux) $ export OSG_ROOT=<osg_sdk_folder>
  • Run commands below in terminal:
    • $ cd <osgverse_folder>
    • $ mkdir build
    • $ cd build
    • $ cmake ..
    • $ cmake --build .
  • You may also choose to use cmake-gui and set OSG related options in GUI mode.
  • For UWP build:
    • First download Windows Store SDK or latest Windows 11 SDK (with VS2022).
    • Download Angle for UWP: https://www.nuget.org/packages/ANGLE.WindowsStore
    • Rename the .nuget file to .zip and extract it. Find libraries and include files there.
    • Build OSG for GLES2/GLES3 (Desktop / GoogleAngle). See herlps/osg_builder/README.md for details.
    • Run commands below in terminal:
      • $ cmake -G "Visual Studio 17 2022" -DCMAKE_SYSTEM_NAME=WindowsStore -DCMAKE_SYSTEM_VERSION="10.0" <osgverse_folder>
  1. Desktop Mac OSX
  • TBD...
  1. Android
  • TBD...
  1. IOS
  • TBD...
  1. WebAssembly
  • Download emsdk from https://emscripten.org/docs/getting_started/downloads.html, extracting to <emsdk_folder>.
  • Update and activate emsdk as required at the page above.
  • Build dependencies and save to <osgverse_folder>/../Dependencies/wasm
  • Download OSG source code and extract it to <osgverse_folder>/../OpenSceneGraph
  • (Optional) Download osgEarth-WASM source code and extract it to <osgverse_folder>/../osgearth-wasm
  • Under Windows with Ninja:
    • Run commands below in terminal:
      • $ <emsdk_folder>/emsdk_env.bat
      • $ cd <osgverse_folder>
      • $ ./Setup.bat
  • Under Linux or WSL (Windows Sub-System for Linux):
    • Start a UNIX ternimal (under Windows, please install WSL v1 and start it).
    • Run commands below in terminal:
      • $ cd <osgverse_folder>
      • $ ./Setup.sh <emsdk_folder>
  • Select "3. WASM / WebGL 1.0" or "4. WASM / WebGL 2.0" and starting building WASM at <osgverse_folder>/build/verse_wasm.
  • Start an HTTPS server at <osgverse_folder>/build/verse_wasm/bin. See <osgverse_folder>/wasm/run_webserver.py as an example.
  • Copy <osgverse_folder>/assets to the same root folder of the server, and enjoy our WebGL examples.

CMake options

Option Type Default Value Notes
OSG_INCLUDE_DIR Path (Required) Set to path of osg/Node
OSG_BUILD_INCLUDE_DIR Path (Required) Set to path of osg/Version
OSG_LIB_DIR Path (Required) Set to path of libosg.a or osg.lib
OSG_DEBUG_POSTFIX String d Set a postfix for OSG debug built-libraries
OSG_GLES_INCLUDE_DIR Path Set to path of GLES2/gl2.h or GLES3/gl3.h, for GLES build only
OSG_GLES_LIBRARY Path Set to path of libGLESv2.so or libGLESv2.lib, for GLES build only
OSG_EGL_LIBRARY Path Set to path of libEGL.so or libEGL.lib, for GLES build only
BULLET_INCLUDE_DIR Path Set to path of btBulletDynamicsCommon.h
BULLET_LIB_DIR Path Set to path of libBulletDynamics.a or BulletDynamics.lib
BULLET_DEBUG_POSTFIX String _Debug Set a postfix for Bullet debug built-libraries
DRACO_INCLUDE_DIR Path Set to path of draco/draco_features.h
DRACO_LIB_DIR Path Set to path of libdraco.a or draco.lib
LIBIGL_INCLUDE_DIR Path Set to path of igl/igl_inline.h
ZLMEDIAKIT_INCLUDE_DIR Path Set to path of mk_common.h
ZLMEDIAKIT_LIB_DIR Path Set to path of libmk_api.so or mk_api.lib
OPENVDB_INCLUDE_DIR Path Set to path of openvdb/openvdb.h
OPENVDB_BOOST_INCLUDE_DIR Path Set to path of boost/type.hpp
OPENVDB_TBB_INCLUDE_DIR Path Set to path of tbb/blocked_range.h
OPENVDB_LIB_DIR Path Set to path of libopenvdb.so or openvdb.lib
OPENVDB_TBB_LIB_DIR Path Set to path of libtbb.so or tbb.lib
OSGEARTH_INCLUDE_DIR Path Set to path of osgEarth/EarthManipulator
OSGEARTH_BUILD_INCLUDE_DIR Path Set to path of osgEarth/BuildConfig
OSGEARTH_LIB_DIR Path Set to path of libosgEarth.so or osgEarth.lib
SDL2_INCLUDE_DIR Path Set to path of SDL.h
SDL2_LIB_DIR Path Set to path of libSDL2.so or SDL2.lib
Qt5_DIR Path Set to path of <qt_dist>/lib/cmake/Qt5
Qt6_DIR Path Set to path of <qt_dist>/lib/cmake/Qt6
VERSE_3RDPARTY_PATH Path Set to path of third-party libraries
VERSE_INSTALL_PDB_FILES Boolean ON Enable to install PDB files along with executables and dynamic libraries
VERSE_BUILD_GPL Boolean OFF Enable build of GPL dependencies, which will makes osgVerse a GPL library
VERSE_BUILD_3RDPARTIES Boolean ON Enable build of common libraries like FreeType, Jpeg and PNG
VERSE_BUILD_WITH_QT Boolean OFF Enable build of Qt based applications and tests
VERSE_BUILD_DEPRECATED_TESTS Boolean OFF Enable build of deprecated tests
VERSE_NO_SIMD_FEATURES Boolean OFF Enable to ignore all SIMD features (when struggling with compile errors)
VERSE_SUPPORT_CPP17 Boolean OFF Enable build of libraries using C++ 17 standard
VERSE_STATIC_BUILD Boolean OFF Enable static build of osgVerse
VERSE_USE_OSG_STATIC Boolean OFF Use static build of OpenSceneGraph (will force osgVerse to be static)
VERSE_USE_DWARF Boolean OFF Enable detailed debug-info and symbols. 'libdw-dev' must be installed
VERSE_USE_GLIBCXX11_ABI Boolean ON Enable to use libraries built with GCC compiler newer than 4.9
VERSE_USE_MTT_DRIVER Boolean OFF Enable to use MooreThreads MTT drivers correctly
VERSE_USE_FORCED_MULTIPLE Boolean OFF Enable to solve LNK2005 problem when compiling OSG 3.2 and lower under MSVC
VERSE_WASM_USE_PTHREAD Boolean ON Enable Pthread for WASM, which requires COOP / COEP on server-side, for WASM build only
VERSE_WASM_OPTIMIZE_SIZE Boolean OFF Enable -O3 for WASM, which is slow but with small generated size
VERSE_FIND_LEGACY_OPENGL Boolean OFF Enable to use legacy mode to search OpenGL libraries, for some Linux systems like Kylin

About

osgVerse, a complete 3d engine solution based on OpenSceneGraph.

Topics

rendering openscenegraph pbr 3d

Resources

Readme

License

MIT license
Activity

Stars

162 stars

Watchers

8 watching

Forks

33 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 5

Languages