version 0.1.0

This is a stable release of the following: - xrlib: core - instance, session, input - xrlib: thread pool manager (helper class for apps to handle multithreading tailored for xr) - xrlib: essential extensions helper classes (vismask, handtracking, fb passthrough, fb triangle mesh, fb display refresh rate) - xrvk: core: pbr rendering (approx ibl only via spherical harmonics), custom pipeline helpers - xrvk: gltf loading via tinygltf, msaa support, multiview rendering as default - xrvk: renderdoc enable/disable, custom shaders (primitives, pbr, sky, floor)
1runeberg · Jan 4, 2025 · 4b5f84b · 4b5f84b
1 parent 716979c
commit 4b5f84b
Show file tree

Hide file tree

Showing 77 changed files with 9,310 additions and 1,112 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,6 @@
 [submodule "third_party/openxr"]
 	path = third_party/openxr
 	url = https://github.com/1runeberg/OpenXR-SDK-xrlib.git
+[submodule "third_party/tinygltf"]
+	path = third_party/tinygltf
+	url = https://github.com/syoyo/tinygltf.git
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,7 +1,13 @@
 # xrlib
-# Copyright 2024 Rune Berg (http://runeberg.io | https://github.com/1runeberg)
-# Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+# Copyright 2024,2025 Copyright Rune Berg 
+# https://github.com/1runeberg | http://runeberg.io | https://runeberg.social | https://www.youtube.com/@1RuneBerg
+# Licensed under Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
 # SPDX-License-Identifier: Apache-2.0
+# 
+# This work is the next iteration of OpenXRProvider (v1, v2)
+# OpenXRProvider (v1): Released 2021 -  https://github.com/1runeberg/OpenXRProvider
+# OpenXRProvider (v2): Released 2022 - https://github.com/1runeberg/OpenXRProvider_v2/
+# v1 & v2 licensed under MIT: https://opensource.org/license/mit
 
 cmake_minimum_required(VERSION 3.22 FATAL_ERROR)
 set(CMAKE_SUPPRESS_REGENERATION true)
@@ -13,7 +19,7 @@ set(CMAKE_SUPPRESS_REGENERATION true)
 
 # Set project variables
 set(XRLIB "xrlib")
-project("${XRLIB}" VERSION 1.0.0.0)
+project("${XRLIB}" VERSION 0.1.0.0)
 
 # Set project directories
 set(XRLIB_ROOT "${CMAKE_CURRENT_SOURCE_DIR}")
@@ -29,6 +35,8 @@ set(XRVK_INCLUDE "${XRLIB_INCLUDE}/xrvk")
 set(XRVK_SRC "${XRLIB_SRC}/xrvk")
 set(XRVK_SHADERS_SRC "${XRLIB_ROOT}/res/shaders/src")
 set(XRVK_SHADERS_BIN "${XRLIB_ROOT}/res/shaders/bin")
+set(XRVK_MODELS_SRC "${XRLIB_ROOT}/res/models/src")
+set(XRVK_MODELS_BIN "${XRLIB_ROOT}/res/models/bin")
 
 # Set project configuration files
 set(XRLIB_CONFIG_IN "${XRLIB_ROOT}/project_config.h.in")
@@ -38,7 +46,7 @@ set(XRLIB_CONFIG_OUT "${XRLIB_INCLUDE}/project_config.h")
 option(BUILD_AS_STATIC "Build as static library" OFF)
 option(BUILD_SHADERS "Build shaders in resource directory" ON)
 option(ENABLE_XRVK "Compile xrvk - pbr render module" ON)
-option(ENABLE_RENDERDOC "Enable renderdoc for render debugs" OFF) 
+option(ENABLE_RENDERDOC "Enable renderdoc for render debugs" ON) 
 option(ENABLE_VULKAN_DEBUG "Enable vulkan debugging" OFF) 
 
 # For windows, we need to override openxr's resource script, so define the rc files here which will be used during binary pre-build
@@ -136,6 +144,10 @@ file(GLOB_RECURSE XRVK_SHADERS
         "${XRVK_SHADERS_SRC}/*.comp"
 	)
 
+file(GLOB_RECURSE XRVK_SHADERS_INCLUDE
+        "${XRVK_SHADERS_SRC}/*.glsl"
+	)
+
 # Compile shaders
 if(NOT ANDROID AND BUILD_SHADERS)
     set(SHADER_OUTPUT_FILES)
@@ -230,8 +242,20 @@ else()
 	message(STATUS "[${XRLIB}] Vulkan library loaded: ${Vulkan_LIBRARY}")
 endif()
 
+# Add openxr
 add_subdirectory(${OPENXR_ROOT})
 
+# Add TinyGLTF
+set(TINYGLTF_USE_CPP14 ON CACHE INTERNAL "" FORCE)
+set(TINYGLTF_HEADER_ONLY ON CACHE INTERNAL "" FORCE)
+set(TINYGLTF_INSTALL OFF CACHE INTERNAL "" FORCE)
+
+if(ANDROID)
+    set(TINYGLTF_ANDROID_LOAD_FROM_ASSETS ON CACHE INTERNAL "" FORCE)
+endif()
+
+add_subdirectory(${THIRD_PARTY}/tinygltf)
+
 
 #####################
 # BINARY DEFINITION #
@@ -247,13 +271,12 @@ source_group(TREE ${XRLIB_SRC} PREFIX src FILES ${XRLIB_SOURCE})
 
 source_group(TREE ${XRVK_INCLUDE} PREFIX xrvk_include FILES ${XRVK_HEADERS})
 source_group(TREE ${XRVK_SRC} PREFIX xrvk_src FILES ${XRVK_SOURCE})
-source_group(TREE ${XRVK_SHADERS_SRC} PREFIX xrvk_shaders FILES ${XRVK_SHADERS})
+source_group(TREE ${XRVK_SHADERS_SRC} PREFIX xrvk_shaders FILES ${XRVK_SHADERS} ${XRVK_SHADERS_INCLUDE})
 
 # Set project config header which contains this project's current version number
 configure_file(${XRLIB_CONFIG_IN} ${XRLIB_CONFIG_OUT})
 message(STATUS "[${XRLIB}] Project version is ${CMAKE_PROJECT_VERSION}")
 
-
 # Assemble all source code (and optional modules/code) that will be compiled for the library
 # See "Set Compile Options" section
 set (ALLSOURCE 
@@ -269,6 +292,7 @@ if(ENABLE_XRVK)
             ${XRVK_HEADERS} 
             ${XRVK_SOURCE} 
             ${XRVK_SHADERS}
+            ${XRVK_SHADERS_INCLUDE}
     )
 
     add_compile_definitions(XRVK_ENABLED)
@@ -347,6 +371,10 @@ else()
                          )
 endif()
 
+    target_link_libraries(${XRLIB} PUBLIC 
+                          tinygltf
+                         )
+
 message(STATUS "[${XRLIB}] Third party libraries linked.")
 
 

diff --git a/README.md b/README.md
@@ -1,9 +1,161 @@
 # xrlib
 [![android-latest](https://github.com/1runeberg/xrlib/actions/workflows/android_builds.yml/badge.svg)](https://github.com/1runeberg/xrlib/actions/workflows/android_builds.yml)&nbsp;&nbsp;[![ubuntu-latest](https://github.com/1runeberg/xrlib/actions/workflows/ubuntu_builds.yml/badge.svg)](https://github.com/1runeberg/xrlib/actions/workflows/ubuntu_builds.yml)&nbsp;&nbsp;[![windows-latest](https://github.com/1runeberg/xrlib/actions/workflows/windows_builds.yml/badge.svg)](https://github.com/1runeberg/xrlib/actions/workflows/windows_builds.yml)
 
- C++20 OpenXR wrapper library designed to abstract the complexities of the OpenXR API while retaining its flexibility, allowing developers to focus on creating immersive experiences without getting bogged down by low-level details. The library is Vulkan-native and includes an optional PBR renderer, designed from the ground up with mixed reality in mind.
+A modern OpenXR wrapper library written in C++20 that streamlines XR development while maintaining OpenXR's full capabilities. Built with native Vulkan support, it abstracts complex API interactions without sacrificing performance or flexibility. 
 
- ## Note
- This repository currently hosts a simplified version of an internal, comprehensive rewrite of [OpenXRProvider_v2](https://github.com/1runeberg/OpenXRProvider_v2).
+The library features an optional physically-based rendering (PBR) engine specifically optimized for mixed reality applications, enabling developers to create high-fidelity immersive experiences with minimal boilerplate code.
 
-The internal library is significantly more advanced but is still in active development as the rewrite is in conjunction with development of a full-featured mixed reality application, scheduled for release by [Beyond Reality Labs](https://beyondreality.io). To avoid backward-incompatible changes, only the most stable components of the rewritten library are made available here.
+Developers can also quickly bootstrap immersive experiences by inheriting from `XrApp` (link to demos), or leverage the library's individual components for custom implementations.
+
+## Demos
+Explore xrlib's capabilities through a collection of example applications available at [xrlib-demos](https://github.com/1runeberg/xrlib-demos). These demos showcase:
+
+- [checkxr](https://github.com/1runeberg/xrlib-demos/tree/main/demo-01_checkxr) - Runtime capability querying and inspection
+- [displayxr](https://github.com/1runeberg/xrlib-demos/tree/main/demo-02_displayxr) - Basic XR visualization and rendering
+- [passthroughxr](https://github.com/1runeberg/xrlib-demos/tree/main/demo-03_passthroughxr) - Meta Quest Passthrough implementation 
+- [handtrackingxr](https://github.com/1runeberg/xrlib-demos/tree/main/demo-04_handtrackingxr) - Hand tracking visualization
+- [inputxr](https://github.com/1runeberg/xrlib-demos/tree/main/demo-05_inputxr) - Full-featured input handling, multi-threading via xrlib's xr dynamic thread pool manager, and PBR rendering
+
+Each demo provides clear, practical implementation examples designed to highlight specific xrlib features. Desktop (Windows, Linux) and Android builds are supported for all demos.
+
+## Building
+
+### Prerequisites
+
+1. Required Tools
+    - CMake 3.22 or higher
+    - C++20 compatible compiler
+    - Vulkan SDK (from [https://vulkan.lunarg.com/](https://vulkan.lunarg.com/))
+    - glslc (Vulkan shader compiler, included in Vulkan SDK)
+
+2. Optional Tools
+    - RenderDoc (if building with debug features)
+
+### Building the Library
+
+1. Clone the Repository
+    ```bash
+    git clone [repository-url]
+    cd xrlib
+    ```
+
+2. Configure Build Options
+
+The following CMake options are available:
+
+#### Basic Options
+    - `BUILD_AS_STATIC`: Build as static library (default: OFF)
+    - `BUILD_SHADERS`: Build shaders in resource directory (default: ON)
+    - `ENABLE_XRVK`: Compile xrvk - PBR render module (default: ON)
+
+#### Debug Options (Desktop only)
+    - `ENABLE_RENDERDOC`: Enable RenderDoc for render debugging (default: ON)
+    - `ENABLE_VULKAN_DEBUG`: Enable Vulkan debugging (default: OFF)
+
+#### Extension Exclusion Options
+    - `EXCLUDE_KHR_VISIBILITY_MASK`: Exclude KHR visibility mask extension (default: OFF)
+    - `EXCLUDE_EXT_HAND_TRACKING`: Exclude hand tracking extension (default: OFF)
+    - `EXCLUDE_FB_DISPLAY_REFRESH`: Exclude display refresh rate extension (default: OFF)
+    - `EXCLUDE_FB_PASSTHROUGH`: Exclude passthrough extension (default: OFF)
+
+3. Configure and Build
+
+#### Windows
+    ```bash
+    # Create build directory
+    mkdir build
+    cd build
+
+    # Configure with CMake
+    cmake ..
+
+    # Build
+    cmake --build . --config Release
+    ```
+
+#### Linux
+    ```bash
+    # Create build directory
+    mkdir build
+    cd build
+
+    # Configure with CMake
+    cmake ..
+
+    # Build
+    make
+    ```
+
+#### Android
+Additional requirements:
+    - Android NDK
+    - Android native app glue
+
+    ```bash
+    # Create build directory
+    mkdir build
+    cd build
+
+    # Configure with CMake (adjust paths as needed)
+    cmake .. -DANDROID=ON -DANDROID_NDK=/path/to/ndk
+
+    # Build
+    cmake --build .
+    ```
+
+4. Output Locations
+
+After successful build, you'll find the outputs in:
+    - Binaries: `./bin/`
+    - Libraries: `./lib/`
+    - Shader binaries (if enabled): `./res/shaders/bin/`
+
+## Advanced Configuration
+
+### Custom Build Configuration Example
+```bash
+cmake .. \
+    -DBUILD_AS_STATIC=ON \
+    -DENABLE_VULKAN_DEBUG=ON \
+    -DEXCLUDE_FB_PASSTHROUGH=ON
+```
+
+### Debug Build
+```bash
+# Configure debug build
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+
+# Build
+cmake --build . --config Debug
+```
+
+## Verification
+
+To verify your build:
+1. Check that the library files exist in the `lib` directory
+2. If building with shaders enabled, verify shader `.spv` files exist in `res/shaders/bin`
+3. For debug builds, ensure debug symbols are present
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Vulkan SDK Not Found**
+   - Ensure Vulkan SDK is installed
+   - Verify `VULKAN_SDK` environment variable is set correctly
+
+2. **Shader Compilation Fails**
+   - Verify `glslc` is in your PATH
+   - Check shader source files in `res/shaders/src`
+
+3. **Android Build Issues**
+   - Verify NDK path is correct
+   - Ensure native app glue is available in NDK
+
+## Development
+
+When developing with the library:
+    - Header files are in `include` directory
+    - Source files are in `src` directory
+    - Shader sources are in `res/shaders/src`
+    - Build artifacts are placed in `bin` and `lib` directories
diff --git a/include/project_config.h b/include/project_config.h
@@ -1,7 +1,7 @@
 #define XRLIB_NAME "xrlib"
 
-#define XRLIB_VERSION_MAJOR 1
-#define XRLIB_VERSION_MINOR 0
+#define XRLIB_VERSION_MAJOR 0
+#define XRLIB_VERSION_MINOR 1
 #define XRLIB_VERSION_PATCH 0
 #define XRLIB_VERSION_TWEAK 0
 

diff --git a/include/xrlib.hpp b/include/xrlib.hpp
@@ -1,11 +1,18 @@
 /* 
- * xrlib
- * Copyright 2024 Rune Berg (http://runeberg.io | https://github.com/1runeberg)
- * Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+ * Copyright 2024,2025 Copyright Rune Berg 
+ * https://github.com/1runeberg | http://runeberg.io | https://runeberg.social | https://www.youtube.com/@1RuneBerg
+ * Licensed under Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
  * SPDX-License-Identifier: Apache-2.0
+ * 
+ * This work is the next iteration of OpenXRProvider (v1, v2)
+ * OpenXRProvider (v1): Released 2021 -  https://github.com/1runeberg/OpenXRProvider
+ * OpenXRProvider (v2): Released 2022 - https://github.com/1runeberg/OpenXRProvider_v2/
+ * v1 & v2 licensed under MIT: https://opensource.org/license/mit
 */
 
+
 #pragma once
 
 #include <xrlib/session.hpp>
+#include <xrlib/input.hpp>
 #include <xrlib/vulkan.hpp>
diff --git a/include/xrlib/common.hpp b/include/xrlib/common.hpp
@@ -1,9 +1,16 @@
 /* 
- * Copyright 2024 Rune Berg (http://runeberg.io | https://github.com/1runeberg)
- * Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+ * Copyright 2024,2025 Copyright Rune Berg 
+ * https://github.com/1runeberg | http://runeberg.io | https://runeberg.social | https://www.youtube.com/@1RuneBerg
+ * Licensed under Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
  * SPDX-License-Identifier: Apache-2.0
+ * 
+ * This work is the next iteration of OpenXRProvider (v1, v2)
+ * OpenXRProvider (v1): Released 2021 -  https://github.com/1runeberg/OpenXRProvider
+ * OpenXRProvider (v2): Released 2022 - https://github.com/1runeberg/OpenXRProvider_v2/
+ * v1 & v2 licensed under MIT: https://opensource.org/license/mit
 */
 
+
 #pragma once
 
 #define XR_USE_GRAPHICS_API_VULKAN 1
@@ -12,6 +19,7 @@
 
 #include <cassert>
 #include <cmath>
+#include <future>
 #include <vulkan/vulkan.h>
 
 #ifndef M_PI
@@ -36,6 +44,8 @@
 
 namespace xrlib
 {
+	inline static float GetLength( const XrVector4f *v ) { return sqrtf( v->x * v->x + v->y * v->y + v->z * v->z + v->w * v->w ); }
+
 	static const float GetDistance( XrVector3f &a, XrVector3f &b ) 
 	{
 		float dx = a.x - b.x;

diff --git a/include/xrlib/data_types.hpp b/include/xrlib/data_types.hpp
@@ -1,8 +1,13 @@
-
 /* 
- * Copyright 2024 Rune Berg (http://runeberg.io | https://github.com/1runeberg)
- * Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+ * Copyright 2024,2025 Copyright Rune Berg 
+ * https://github.com/1runeberg | http://runeberg.io | https://runeberg.social | https://www.youtube.com/@1RuneBerg
+ * Licensed under Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
  * SPDX-License-Identifier: Apache-2.0
+ * 
+ * This work is the next iteration of OpenXRProvider (v1, v2)
+ * OpenXRProvider (v1): Released 2021 -  https://github.com/1runeberg/OpenXRProvider
+ * OpenXRProvider (v2): Released 2022 - https://github.com/1runeberg/OpenXRProvider_v2/
+ * v1 & v2 licensed under MIT: https://opensource.org/license/mit
 */
 
 #pragma once

diff --git a/include/xrlib/data_types_bitmasks.hpp b/include/xrlib/data_types_bitmasks.hpp
@@ -1,20 +1,16 @@
 /* 
- * Copyright 2023-24 Beyond Reality Labs Ltd (https://beyondreality.io)
- * Copyright 2021-24 Rune Berg (GitHub: https://github.com/1runeberg, YT: https://www.youtube.com/@1RuneBerg, X: https://twitter.com/1runeberg, BSky: https://runeberg.social)
+ * Copyright 2024,2025 Copyright Rune Berg 
+ * https://github.com/1runeberg | http://runeberg.io | https://runeberg.social | https://www.youtube.com/@1RuneBerg
+ * Licensed under Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
+ * SPDX-License-Identifier: Apache-2.0
  * 
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- * 
- * http://www.apache.org/licenses/LICENSE-2.0
- * 
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * This work is the next iteration of OpenXRProvider (v1, v2)
+ * OpenXRProvider (v1): Released 2021 -  https://github.com/1runeberg/OpenXRProvider
+ * OpenXRProvider (v2): Released 2022 - https://github.com/1runeberg/OpenXRProvider_v2/
+ * v1 & v2 licensed under MIT: https://opensource.org/license/mit
 */
 
+
 #pragma once
 #include <stdint.h>