1 files changed, 83 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..004dbfd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# bionic-fg
+
+Standalone Android/Bionic Vulkan frame generation layer.
+
+## What is here
+
+- `libbionic_fg.so`: native framegen runtime and Vulkan implicit layer
+- `VK_LAYER_BIONIC_framegen`: intercepts swapchain presentation and injects generated frames
+- Android Hardware Buffer sharing between the producer Vulkan device and the framegen device
+- Embedded SPIR-V shader bundle with model 0 and model 1 selection
+- Optional JNI bootstrap API under `io.github.bionicfg.BionicFGNative`
+
+## Runtime configuration
+
+The Vulkan layer is enabled with `BIONIC_FG_ENABLE=1` and reads a TOML config file.
+The config path defaults to `$HOME/.config/bionic-fg/conf.toml` and can be overridden with `BIONIC_FG_CONFIG`.
+
+```sh
+BIONIC_FG_ENABLE=1
+BIONIC_FG_CONFIG=/path/to/conf.toml # optional
+VK_LAYER_PATH=/path/to/implicit_layer.d
+```
+
+```toml
+version = 1
+
+[global]
+enabled = true
+multiplier = 2   # 0=off, or 2..4
+flow_scale = 0.8 # 0.2..1.0
+model = 0        # 0 or 1
+```
+
+For backwards compatibility, `BIONIC_FG_MULTIPLIER`, `BIONIC_FG_FLOW_SCALE`, and
+`BIONIC_FG_MODEL` are still accepted when the TOML file is missing. If the TOML
+file exists, it wins.
+
+The layer polls the config file timestamp during presentation.
+- `flow_scale` hot-reloads in place.
+- `multiplier` and `model` hot-reload by rebuilding the internal framegen
+  context against the already-provisioned AHB outputs and swapchain image pool.
+  Setting `multiplier = 0` turns frame generation off without recreating the
+  app swapchain.
+- `enabled` still returns `VK_ERROR_OUT_OF_DATE_KHR` once so the application
+  can recreate its swapchain with or without the layer active.
+
+Install layout expected by the manifest:
+
+```text
+.local/lib/libbionic_fg.so
+.local/share/vulkan/implicit_layer.d/VkLayer_BIONIC_framegen.json
+```
+
+The manifest uses `../../../lib/libbionic_fg.so` relative to `implicit_layer.d`.
+
+## Build
+
+```sh
+cmake -S . -B build/android-arm64 \
+  -DANDROID_ABI=arm64-v8a \
+  -DANDROID_PLATFORM=android-26 \
+  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+cmake --build build/android-arm64 -j
+```
+
+## Shaders
+
+The compute shaders are a clean-room reimplementation of the shader *code*:
+functional specifications were derived from disassembly of the runtime-traced
+shaders, and the GLSL in `cleanroom/glsl/` was written from those
+specifications alone, by implementers who did not see the originals, then
+compiled with glslc. See `cleanroom/PROCESS.md`.
+
+The numeric weight constants are carried over from the original shaders as
+functional parameters — the reimplementation reproduces their behavior
+bit-exactly. No third-party compiled shader artifacts are shipped.
+
+## License
+
+GPL-3.0. See `LICENSE`.
+
+Originally written by xXJSONDeruloXx (https://github.com/xXJSONDeruloXx/bionic-fg)
+with contributions from The412Banner; extended for GameNative by Utkarsh Dalal.