wip

studio_cli/assets/skyboxes/README.md

@@ -0,0 +1,54 @@
+# Generating Skybox and Image-Based Lighting Assets
+
+HDRI images like those available at [Poly Haven](https://polyhaven.com/hdris/skies)
+or [HDRI Haven](https://hdri-haven.com) must be preprocessed before they can be
+used for skyboxes and image-based lighting in Bevy Engine. Ultimately, three
+files are required:
+
+* An `*.hdr` cubemap texture for the skybox
+* A `*.ktx2` prefiltered diffuse irradiance cubemap for IBL
+* A `*.ktx2` prefiltered specular cubemap for IBL
+
+The HDR cubemap texture currently must be generated using Blender. A helper
+asset with instructions is available [here](https://drive.google.com/file/d/1UG_w9a6XfRmZtcfsSwFTDWPF7KnRa56I/view?usp=sharing)
+for Blender 3.6.
+
+The prefiltered IBL cubemaps are generated with two CLI tools:
+
+1. [glTF IBL Sampler](https://github.com/KhronosGroup/glTF-IBL-Sampler)
+	* Git clone with `--recursive` and build using CMake
+	* Diffuse:
+	```sh
+	./path/to/build-output/cli \
+		-inputPath <input>.hdr \
+		-outCubeMap <output>_diffuse.ktx2 \
+		-distribution Lambertian \
+		-cubeMapResolution 32
+	```
+	* Specular:
+	```sh
+	./path/to/build-output/cli \
+		-inputPath <input>.hdr \
+		-outCubeMap <output>_specular.ktx2 \
+		-distribution GGX \
+		-cubeMapResolution 512
+	```
+
+2. [bevy_mod_environment_map_tools](https://github.com/DGriffin91/bevy_mod_environment_map_tools)
+	* You can run this directly with `cargo` on the files generated by the
+	previous step:
+	```sh
+	cargo run --release -- \
+		--inputs <input>_diffuse.ktx2,<input>_specular.ktx2 \
+		--outputs <output>_diffuse.zstd.ktx2,<output>_specular.zstd.ktx2
+	```
+
+The Bevy app expects the filenames to exactly match the patterns given in the
+examples above:
+
+* `{name}.hdr`
+* `{name}_diffuse.zstd.ktx2`
+* `{name}_specular.zstd.ktx2`
+
+Once the files are in place, the application's `skybox` module can load all of
+the associated files for a skybox by passing its `name` to a helper function.