repository·master·Indexed 21 days ago
https://github.com/babylonjs/babylonnativeBabylon Native enables developers to run Babylon.js JavaScript code in native environments including Windows, macOS, iOS, Android, and Linux. The library includes tools for headless rendering via HeadlessScreenshotApp, shader validation with PrecompiledShaderTest, and native graphics integration through the ExternalTexture plugin for passing native API texture objects (such as D3D12 resources) into the Babylon engine.
ShaderCompiler for compilation and ShaderCache to save the results. It is specifically designed to be integrated into automated build processes, allowing you to bundle multiple shader pairs into a single compiled cache file.ExternalTexture plugin library allows you to pass native graphics API texture objects (like D3D12 resources) into Babylon Native. This enables BabylonJS to use textures created by your native hosting application. By using Babylon::Plugins::ExternalTexture, you can generate JavaScript objects that the Babylon engine can consume as textures.Babylon Native Polyfills provide implementations for specific JavaScript browser APIs that are required by Babylon.js or commonly used by its developers.
Important Limitations:
Currently supported polyfills include:
CanvasConsoleWindowXMLHttpRequestIn Babylon Native, JsRuntime is an abstraction that provides an integration point for interacting with a JavaScript engine and its dedicated thread, but it does not provide the implementation itself.
AppRuntime is the canonical implementation that underlies a JsRuntime. It manages the entire lifecycle and infrastructure required for a Babylon Native app, including:
JsRuntime to provide access to these resources.For most dedicated Babylon Native scenarios, creating an AppRuntime is the recommended way to control JavaScript in a manner that is easily consumable by other Babylon Native components.
The NativeEngine component is the core rendering bridge in Babylon Native. While JsRuntime and AppRuntime provide the infrastructure for running web logic on native, NativeEngine is the specific component that interfaces with Babylon.js to power its rendering capabilities.
Key characteristics:
Engine abstraction.Engine and low-level native graphics APIs.Babylon Native's NativeEngine bridges the gap between Babylon.js's ESSL shaders (designed for WebGL) and the native shader languages required by the underlying bgfx graphics abstraction (HLSL, GLSL, MSL, etc.).
To achieve this, NativeEngine performs runtime transpilation by converting ESSL source code into platform-specific native shaders. This allows developers to use standard Babylon.js shader code while running on native platforms like DirectX, OpenGL, or Metal.
Babylon Native uses a modular, componentized architecture organized into four principle categories. This structure supports lateral dependency management, allowing components to be assembled, excluded, or replaced easily.
Dependencies: Contains external or pre-existing code that may not follow Babylon Native's lateral patterns. It includes "adapter" mechanisms (via CMakeLists.txt) to allow these external libraries to be consumed as standard CMake targets by other components.Core: Foundational components that expose functionality to the native (C++) layer. They must have no dependencies outside of Core and Dependencies. An example is JsRuntime.Plugins: Components that expose functionality to the JavaScript layer, often by exposing new types (e.g., via N-API). They can have many dependencies across Plugins, Core, and Dependencies. The NativeEngine is the primary plugin.Polyfills: Components that provide implementations for pre-existing JavaScript capabilities (like console.log or browser features).Critical Constraint: No Babylon Native C++ component is allowed to depend on a Polyfill.
To support multiple native platforms, NativeEngine uses bgfx (along with bimg and bx) as its underlying graphics abstraction.
bgfx allows NativeEngine to write a single translation layer that connects the Babylon.js Engine abstraction to various native graphics APIs (targeting every major native graphics API).NativeEngine includes a specialized mechanism to transpile Babylon.js WebGL shaders into the appropriate languages for the target platform. This is handled internally and does not affect the public-facing API.Unlike a WebGL polyfill that attempts to mimic the WebGL API at the lowest level, Babylon Native integrates at the Engine level. This approach minimizes the integration surface area and allows for customizations on both the JavaScript and native sides.
NativeEngine type to JavaScript.NativeEngine JavaScript type. This type is aware of the native constructor and manages a native NativeEngine instance internally.NativeEngine uses the backing C++ instance to execute all rendering work required by a Babylon.js Engine.Because this integration happens at the Engine abstraction level, code targeting traditional web-based engines can typically run on Babylon Native without any changes.
Babylon Native supports two primary integration patterns via JsRuntime:
AppRuntime) owns both the JavaScript engine and the thread it runs on.JsRuntime is implemented to interface with a pre-existing JavaScript engine and thread managed by the host (e.g., React Native's engine), allowing Babylon Native components to function without controlling the host's environment.