# 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.