OpenXR SDK地址为:GitHub - KhronosGroup/OpenXR-SDK-Source: Sources for OpenXR loader, basic API layers, and example code.
Monado runtime地址为:Monado / Monado · GitLab
system broker地址为:Ryan Pavlik / openxr-android-broker · GitLab
本文主要讲解openxr应用如何选择monado runtime的主要流程。
CreateInstance流程如下
具体流程如下
目录
5. xrEnumerateInstanceExtensionProperties
6. LoaderXrEnumerateInstanceExtensionProperties
7. RuntimeInterface::LoadRuntime-查找并加载runtime
8. RuntimeManifestFile::FindManifestFiles--查找runtime
9. GetPlatformRuntimeVirtualManifest--查找runtime-标志1
10. getActiveRuntimeVirtualManifest--查找runtime-标志1
11. PlatformGetGlobalRuntimeFileName--查找runtime-标志3
14. TryLoadingSingleRuntime--加载runtime-标志3
以SDK中的hello_xr应用为例,其入口在main.cpp中
1.实例化OpenXrProgram
main.cpp void android_main(struct android_app* app) { ... // Initialize the OpenXR program. //实例化OpenXrProgram std::shared_ptr<IOpenXrProgram> program = CreateOpenXrProgram(options, platformPlugin, graphicsPlugin); // Initialize the loader for this platform PFN_xrInitializeLoaderKHR initializeLoader = nullptr; //将LoaderXrInitializeLoaderKHR方法指针赋值给initializeLoader if (XR_SUCCEEDED( xrGetInstanceProcAddr(XR_NULL_HANDLE, "xrInitializeLoaderKHR", (PFN_xrVoidFunction*)(&initializeLoader)))) { XrLoaderInitInfoAndroidKHR loaderInitInfoAndroid = {XR_TYPE_LOADER_INIT_INFO_ANDROID_KHR}; loaderInitInfoAndroid.applicationVM = app->activity->vm; loaderInitInfoAndroid.applicationContext = app->activity->clazz; //执行LoaderXrInitializeLoaderKHR方法 initializeLoader((const XrLoaderInitInfoBaseHeaderKHR*)&loaderInitInfoAndroid); } //CreateInstance program->CreateInstance(); program->InitializeSystem(); ... }
2. CreateOpenXrProgram
openxr_program.cpp
std::shared_ptr<IOpenXrProgram> CreateOpenXrProgram(const std::shared_ptr<Options>& options, const std::shared_ptr<IPlatformPlugin>& platformPlugin, const std::shared_ptr<IGraphicsPlugin>& graphicsPlugin) { //make_shared函数的主要功能是在动态内存中分配一个对象并初始化它,返回指向此对象的shared_ptr;由于是通过shared_ptr管理内存,因此一种安全分配和使用动态内存的方法。 return std::make_shared<OpenXrProgram>(options, platformPlugin, graphicsPlugin); }struct OpenXrProgram : IOpenXrProgram { OpenXrProgram(const std::shared_ptr<Options>& options, const std::shared_ptr<IPlatformPlugin>& platformPlugin, const std::shared_ptr<IGraphicsPlugin>& graphicsPlugin) : m_options(options),//赋值 m_platformPlugin(platformPlugin), m_graphicsPlugin(graphicsPlugin), m_acceptableBlendModes{XR_ENVIRONMENT_BLEND_MODE_OPAQUE, XR_ENVIRONMENT_BLEND_MODE_ADDITIVE, XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND} {}
3. 实例化后会CreateInstance
openxr_program.cpp void CreateInstance() override { LogLayersAndExtensions(); CreateInstanceInternal(); LogInstanceInfo(); }
4. LogLayersAndExtensions
openxr_program.cpp static void LogLayersAndExtensions() { // Write out extension properties for a given layer. const auto logExtensions = [](const char* layerName, int indent = 0) { uint32_t instanceExtensionCount; //CHECK_XRCMD是用于判断函数是否执行FAILED //xrEnumerateInstanceExtensionProperties返回可用实例扩展的属性 CHECK_XRCMD(xrEnumerateInstanceExtensionProperties(layerName, 0, &instanceExtensionCount, nullptr)); ...... }
5. xrEnumerateInstanceExtensionProperties
loader_core.cpp LOADER_EXPORT XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char *layerName, uint32_t propertyCapacityInput, uint32_t *propertyCountOutput, XrExtensionProperties *properties) { return LoaderXrEnumerateInstanceExtensionProperties(layerName, propertyCapacityInput, propertyCountOutput, properties); }
6. LoaderXrEnumerateInstanceExtensionProperties
loader_core.cpp static XRAPI_ATTR XrResult XRAPI_CALL LoaderXrEnumerateInstanceExtensionProperties(const char *layerName, uint32_t propertyCapacityInput, uint32_t *propertyCountOutput, XrExtensionProperties *properties) XRLOADER_ABI_TRY { ... // Get the layer extension properties result = ApiLayerInterface::GetInstanceExtensionProperties("xrEnumerateInstanceExtensionProperties", layerName, extension_properties); if (XR_SUCCEEDED(result) && !just_layer_properties) { // If not specific to a layer, get the runtime extension properties //如果不是特定于某个层,则获取运行时扩展属性 result = RuntimeInterface::LoadRuntime("xrEnumerateInstanceExtensionProperties"); if (XR_SUCCEEDED(result)) { RuntimeInterface::GetRuntime().GetInstanceExtensionProperties(extension_properties); ... }
7. RuntimeInterface::LoadRuntime-查找并加载runtime
runtime_interface.cpp XrResult RuntimeInterface::LoadRuntime(const std::string& openxr_command) { // If something's already loaded, we're done here. //如果已经有Instance实例了,则return, 这代表一个APP只有一个Instance实例 if (GetInstance() != nullptr) { return XR_SUCCESS; } #ifdef XR_KHR_LOADER_INIT_SUPPORT if (!LoaderInitData::instance().initialized()) {//Instance没有成功初始化 LoaderLogger::LogErrorMessage( openxr_command, "RuntimeInterface::LoadRuntime cannot run because xrInitializeLoaderKHR was not successfully called."); return XR_ERROR_INITIALIZATION_FAILED; } #endif // XR_KHR_LOADER_INIT_SUPPORT std::vector<std::unique_ptr<RuntimeManifestFile>> runtime_manifest_files = {}; // Find the available runtimes which we may need to report information for. //查找可用的runtime,会对runtime_manifest_files赋值 XrResult last_error = RuntimeManifestFile::FindManifestFiles(runtime_manifest_files); if (XR_FAILED(last_error)) { LoaderLogger::LogErrorMessage(openxr_command, "RuntimeInterface::LoadRuntimes - unknown error"); } else { last_error = XR_ERROR_RUNTIME_UNAVAILABLE; for (std::unique_ptr<RuntimeManifestFile>& manifest_file : runtime_manifest_files) { //加载runtime-----标志5 last_error = RuntimeInterface::TryLoadingSingleRuntime(openxr_command, manifest_file); if (XR_SUCCEEDED(last_error)) { break; } } } // Unsuccessful in loading any runtime, throw the runtime unavailable message. //如果没有加载到任何的runtime,会返回错误,且应用无法正常运转,表现大多为黑屏,或者卡在启动动画上 if (XR_FAILED(last_error)) { LoaderLogger::LogErrorMessage(openxr_command, "RuntimeInterface::LoadRuntimes - failed to load a runtime"); last_error = XR_ERROR_RUNTIME_UNAVAILABLE; } return last_error; }
8. RuntimeManifestFile::FindManifestFiles--查找runtime
manifest_file.cpp // Find all manifest files in the appropriate search paths/registries for the given type. XrResult RuntimeManifestFile::FindManifestFiles(std::vector<std::unique_ptr<RuntimeManifestFile>> &manifest_files) { #if defined(XR_KHR_LOADER_INIT_SUPPORT) Json::Value virtualManifest; //获取runtime result = GetPlatformRuntimeVirtualManifest(virtualManifest);//标志1 if (XR_SUCCESS == result) { //将获取到的virtualManifest中的信息赋值给manifest_files RuntimeManifestFile::CreateIfValid(virtualManifest, "", manifest_files);//标志2 return result; } #endif // defined(XR_KHR_LOADER_INIT_SUPPORT) //如果上面通过GetPlatformRuntimeVirtualManifest没有找到runtime,则会通过PlatformGetGlobalRuntimeFileName继续查找 if (!PlatformGetGlobalRuntimeFileName(XR_VERSION_MAJOR(XR_CURRENT_API_VERSION), filename)) {//标志3 LoaderLogger::LogErrorMessage( "", "RuntimeManifestFile::FindManifestFiles - failed to determine active runtime file path for this environment"); return XR_ERROR_RUNTIME_UNAVAILABLE; } result = XR_SUCCESS; LoaderLogger::LogInfoMessage("", "RuntimeManifestFile::FindManifestFiles - using global runtime file " + filename); #endif } //将filename文件中的信息赋值给manifest_files RuntimeManifestFile::CreateIfValid(filename, manifest_files);//标志4 ... }
9. GetPlatformRuntimeVirtualManifest--查找runtime-标志1
runtime_interface.cpp #ifdef XR_USE_PLATFORM_ANDROID XrResult GetPlatformRuntimeVirtualManifest(Json::Value& out_manifest) { using wrap::android::content::Context; auto& initData = LoaderInitData::instance(); if (!initData.initialized()) { return XR_ERROR_INITIALIZATION_FAILED; } auto context = Context(reinterpret_cast<jobject>(initData.getData().applicationContext)); if (context.isNull()) { return XR_ERROR_INITIALIZATION_FAILED; } Json::Value virtualManifest; //即将通过Cursor要去查系统中的runtime了 if (0 != openxr_android::getActiveRuntimeVirtualManifest(context, virtualManifest)) { return XR_ERROR_INITIALIZATION_FAILED; } //virtualManifest赋值给out_manifest out_manifest = virtualManifest; return XR_SUCCESS; } #endif // XR_USE_PLATFORM_ANDROID
10. getActiveRuntimeVirtualManifest--查找runtime-标志1
android_utilities.cpp
int getActiveRuntimeVirtualManifest(wrap::android::content::Context const &context, Json::Value &virtualManifest) { jni::Array<std::string> projection = makeArray({active_runtime::Columns::PACKAGE_NAME,active_runtime::Columns::NATIVE_LIB_DIR, active_runtime::Columns::SO_FILENAME, active_runtime::Columns::HAS_FUNCTIONS}); // First, try getting the installable broker's provider bool systemBroker = false; Cursor cursor; //log输出:08-02 08:43:48.651 4294 4331 I OpenXR-Loader: getActiveRuntimeCursor: Querying URI: content://org.khronos.openxr.runtime_broker/openxr/1/abi/arm64-v8a/runtimes/active/0 //非系统应用 if (!getActiveRuntimeCursor(context, projection, systemBroker, cursor)) { // OK, try the system broker as a fallback. //是系统应用,不是通过用户去安装的 systemBroker = true; getActiveRuntimeCursor(context, projection, systemBroker, cursor); //log输出:08-02 08:43:48.654 4294 4331 I OpenXR-Loader: getActiveRuntimeCursor: Querying URI: content://org.khronos.openxr.system_runtime_broker/openxr/1/abi/arm64-v8a/runtimes/active/0 } if (cursor.isNull()) { // Couldn't find either broker ALOGE("Could access neither the installable nor system runtime broker."); return -1; } cursor.moveToFirst(); //通过cursor去查column对应的内容 auto filename = cursor.getString(cursor.getColumnIndex(active_runtime::Columns::SO_FILENAME)); auto libDir = cursor.getString(cursor.getColumnIndex(active_runtime::Columns::NATIVE_LIB_DIR)); auto packageName = cursor.getString(cursor.getColumnIndex(active_runtime::Columns::PACKAGE_NAME)); auto hasFunctions = cursor.getInt(cursor.getColumnIndex(active_runtime::Columns::HAS_FUNCTIONS)) == 1; __android_log_print(ANDROID_LOG_INFO, TAG, "Got runtime: package: %s, so filename: %s, native lib dir: %s, has functions: %s", packageName.c_str(), filename.c_str(), libDir.c_str(), (hasFunctions ? "yes" : "no")); //log输出: 08-02 08:39:29.543 4425 4462 I OpenXR-Loader: Got runtime: package: org.freedesktop.monado.openxr_runtime.out_of_process, so filename: libopenxr_monado.so, native lib dir:/data/app/~~ZNtBhWeJzxYgOPuiZZVjgQ==/org.freedesktop.monado.openxr_runtime.out_of_process-PVkP76Im0S4PZZp5d2Gb5g==/lib/arm64, has functions: no //可以看到通过URI查出来的包名是org.freedesktop.monado.openxr_runtime.out_of_process, 对应的runtime so名字是libopenxr_monado.so auto lib_path = libDir + "/" + filename;//lib_path就是runtime so的全路径 cursor.close(); //创建json文件,并将lib_path传入,root 名为runtime, lib_path为子节点 JsonManifestBuilder builder{"runtime", lib_path}; if (hasFunctions) { int result = populateFunctions(context, systemBroker, packageName, builder); if (result != 0) { return result; } } //json文件创建 virtualManifest = builder.build(); return 0; } } // namespace openxr_android
11. PlatformGetGlobalRuntimeFileName--查找runtime-标志3
platform_utils.hpp 此函数会在"/product", "/odm", "/oem", "/vendor", "/system"目录下的/etc/openxr/下查找active_runtime.json文件 // Intended to be only used as a fallback on Android, with a more open, "native" technique used in most cases static inline bool PlatformGetGlobalRuntimeFileName(uint16_t major_version, std::string& file_name) { // Prefix for the runtime JSON file name static const char* rt_dir_prefixes[] = {"/product", "/odm", "/oem", "/vendor", "/system"}; static const std::string rt_filename = "/active_runtime.json"; static const std::string subdir = "/etc/openxr/"; for (const auto prefix : rt_dir_prefixes) { auto path = prefix + subdir + std::to_string(major_version) + rt_filename; struct stat buf; if (0 == stat(path.c_str(), &buf)) { file_name = path;//返回active_runtime.json所在的目录 return true; } } return false; }
12. CreateIfValid-标志2
manifest_file.cpp void RuntimeManifestFile::CreateIfValid(const Json::Value &root_node, const std::string &filename,std::vector<std::unique_ptr<RuntimeManifestFile>> &manifest_files) { std::ostringstream error_ss("RuntimeManifestFile::CreateIfValid "); JsonVersion file_version = {}; if (!ManifestFile::IsValidJson(root_node, file_version)) { error_ss << "isValidJson indicates " << filename << " is not a valid manifest file."; LoaderLogger::LogErrorMessage("", error_ss.str()); return; } // Json的root节点是runtime,子节点是library_path,如果有一个为空,则return const Json::Value &runtime_root_node = root_node["runtime"]; // The Runtime manifest file needs the "runtime" root as well as a sub-node for "library_path". If any of those aren't there, // fail. if (runtime_root_node.isNull() || runtime_root_node["library_path"].isNull() || !runtime_root_node["library_path"].isString()) { error_ss << filename << " is missing required fields. Verify all proper fields exist."; LoaderLogger::LogErrorMessage("", error_ss.str()); return; } //将子节点library_path的转化为string类型 std::string lib_path = runtime_root_node["library_path"].asString(); // If the library_path variable has no directory symbol, it's just a file name and should be accessible on the // global library path. if (lib_path.find('\\') != std::string::npos || lib_path.find('/') != std::string::npos) { // If the library_path is an absolute path, just use that if it exists //如果lib_path是绝对路径,如果存在则直接使用, 我们上面存的是绝对路径 if (FileSysUtilsIsAbsolutePath(lib_path)) { if (!FileSysUtilsPathExists(lib_path)) { error_ss << filename << " library " << lib_path << " does not appear to exist"; LoaderLogger::LogErrorMessage("", error_ss.str()); return; } } else { ... } } //add manifest files // Add this runtime manifest file manifest_files.emplace_back(new RuntimeManifestFile(filename, lib_path)); // Add any extensions to it after the fact. // Handle any renamed functions manifest_files.back()->ParseCommon(runtime_root_node); }
13. CreateIfValid-标志4
manifest_file.cpp void RuntimeManifestFile::CreateIfValid(std::string const &filename , std::vector<std::unique_ptr<RuntimeManifestFile>> &manifest_files) { std::ifstream json_stream(filename, std::ifstream::in); LoaderLogger::LogInfoMessage("", "RuntimeManifestFile::CreateIfValid - attempting to load " + filename); std::ostringstream error_ss("RuntimeManifestFile::CreateIfValid "); if (!json_stream.is_open()) { error_ss << "failed to open " << filename << ". Does it exist?"; LoaderLogger::LogErrorMessage("", error_ss.str()); return; } Json::CharReaderBuilder builder; std::string errors; Json::Value root_node = Json::nullValue; ... //会调用到12步 CreateIfValid(root_node, filename, manifest_files); }
14. TryLoadingSingleRuntime--加载runtime-标志5
runtime_interface.cpp XrResult RuntimeInterface::TryLoadingSingleRuntime(const std::string& openxr_command, std::unique_ptr<RuntimeManifestFile>& manifest_file) { LoaderPlatformLibraryHandle runtime_library = LoaderPlatformLibraryOpen(manifest_file->LibraryPath());//dlopen runtime so ... #ifdef XR_KHR_LOADER_INIT_SUPPORT if (!LoaderInitData::instance().initialized()) { LoaderLogger::LogErrorMessage(openxr_command, "RuntimeInterface::LoadRuntime skipping manifest file " +manifest_file->Filename() +" because xrInitializeLoaderKHR was not yet called."); ... // If we have xrInitializeLoaderKHR exposed as an export, forward call to it. const auto function_name = manifest_file->GetFunctionName("xrInitializeLoaderKHR"); auto initLoader = reinterpret_cast<PFN_xrInitializeLoaderKHR>(LoaderPlatformLibraryGetProcAddr(runtime_library, function_name));//dlsym if (initLoader != nullptr) {//initLoader为空 ... } } ... // Get and settle on an runtime interface version (using any provided name if required). std::string function_name = manifest_file->GetFunctionName("xrNegotiateLoaderRuntimeInterface"); auto negotiate = reinterpret_cast<PFN_xrNegotiateLoaderRuntimeInterface>(LoaderPlatformLibraryGetProcAddr(runtime_library, function_name));//dlsym ... // Skip calling the negotiate function and fail if the function pointer // could not get loaded XrResult res = XR_ERROR_RUNTIME_FAILURE; if (nullptr != negotiate) { //执行runtime中的xrNegotiateLoaderRuntimeInterface方法 //会对runtime_info结构体中的子变量getInstanceProcAddr赋值,赋值成了runtime中的方法,方法名为oxr_xrGetInstanceProcAddr res = negotiate(&loader_info, &runtime_info); } ... #ifdef XR_KHR_LOADER_INIT_SUPPORT if (XR_SUCCEEDED(res) && !forwardedInitLoader) { // Forward initialize loader call, where possible and if we did not do so before. PFN_xrVoidFunction initializeVoid = nullptr; PFN_xrInitializeLoaderKHR initialize = nullptr; // Now we may try asking xrGetInstanceProcAddr //执行runtime中的oxr_xrGetInstanceProcAddr方法,会将xrInitializeLoaderKHR方法指针赋值为runtime中的oxr_xrInitializeLoaderKHR if (XR_SUCCEEDED(runtime_info.getInstanceProcAddr(XR_NULL_HANDLE, "xrInitializeLoaderKHR", &initializeVoid))) {// if (initializeVoid == nullptr) { LoaderLogger::LogErrorMessage(openxr_command,"RuntimeInterface::LoadRuntime got success from xrGetInstanceProcAddr " "for xrInitializeLoaderKHR, but output a null pointer."); res = XR_ERROR_RUNTIME_FAILURE; } else { //将initializeVoid函数指针赋值给initialize initialize = reinterpret_cast<PFN_xrInitializeLoaderKHR>(initializeVoid); } } if (initialize != nullptr) { // we found the entry point one way or another. LoaderLogger::LogInfoMessage(openxr_command,"RuntimeInterface::LoadRuntime forwarding xrInitializeLoaderKHR call to runtime after calling xrNegotiateLoaderRuntimeInterface."); //执行runtime中的oxr_xrInitializeLoaderKHR方法 res = initialize(LoaderInitData::instance().getParam()); if (!XR_SUCCEEDED(res)) { LoaderLogger::LogErrorMessage(openxr_command,"RuntimeInterface::LoadRuntime forwarded call to xrInitializeLoaderKHR failed."); } } } ... // Use this runtime //使用这个runtime GetInstance().reset(new RuntimeInterface(runtime_library, runtime_info.getInstanceProcAddr)); ... }