{"id":15922104,"url":"https://github.com/nicopap/bevy_mod_paramap","last_synced_at":"2025-08-31T15:05:13.994Z","repository":{"id":59170340,"uuid":"534541287","full_name":"nicopap/bevy_mod_paramap","owner":"nicopap","description":"Experimental extensions to bevy's parallax mapping shader","archived":false,"fork":false,"pushed_at":"2023-03-06T18:27:06.000Z","size":5349,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T03:41:22.993Z","etag":null,"topics":["bevy","rust","shader"],"latest_commit_sha":null,"homepage":"https://nicopap.github.io/bevy_mod_paramap/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicopap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["nicopap"]}},"created_at":"2022-09-09T07:22:03.000Z","updated_at":"2024-11-04T14:46:53.000Z","dependencies_parsed_at":"2024-10-29T00:40:51.740Z","dependency_job_id":"fb1d3e1a-1c50-4b57-99aa-002a08bdb975","html_url":"https://github.com/nicopap/bevy_mod_paramap","commit_stats":{"total_commits":31,"total_committers":2,"mean_commits":15.5,"dds":"0.032258064516129004","last_synced_commit":"191cc32a204090b67332da031624f9aae8a04ea2"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicopap%2Fbevy_mod_paramap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicopap%2Fbevy_mod_paramap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicopap%2Fbevy_mod_paramap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicopap%2Fbevy_mod_paramap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicopap","download_url":"https://codeload.github.com/nicopap/bevy_mod_paramap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245261059,"owners_count":20586515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bevy","rust","shader"],"created_at":"2024-10-06T20:05:05.388Z","updated_at":"2025-03-24T11:32:25.464Z","avatar_url":"https://github.com/nicopap.png","language":"Rust","funding_links":["https://github.com/sponsors/nicopap"],"categories":[],"sub_categories":[],"readme":"## Bevy parallax mapping\n\n[parallax mapping] is a graphical effect adding the impression of depth to\nsimple 2d textures by moving the texture's pixel around according to the\nviewport's perspective.\n\nThis is **NOT** a \"parallax\" à la Super Mario World. This is intended for 3D\nrendering. This technic has been used with success in the Demon's Souls\nBluepoint remake.\n\nThis crate adds a custom material that extends the default bevy PBR material\nwith [parallax mapping]. The [`ParallaxMaterial`] asset is a straight copy\nof bevy's PBR material with the addition of the `height_map: Handle\u003cImage\u003e`\nfiled (it's not `Option` since you might as well use the default shader if\nthere is no height maps).\n\n`height_map` is a greyscale image representing the height of the object at the\nspecific pixel.\n\n[`ParallaxMaterial`] allows selecting the algorithm used for parallaxing. By\nsetting the [`algorithm`] field to the [`ParallaxAlgo`] of your choosing, you\nmay opt into using Relief Mapping. By default, [`ParallaxMaterial`] uses the\nParallax Occlusion Mapping (POM) method. (see the shader source code for\nexplanation on what the algorithms do)\n\n### Examples\n\nThis repo contains two examples.\n\n```bash\ncargo run --example \u003cexample_name\u003e\n```\n\n- [`earth3d`]: a spinning view of the earth. Takes advantage of height map,\n  but also of all the bevy PBR fields. This a good demonstration of bevy's\n  capabilities.\n  \\\n  You can orbit the earth by holding down the right mouse button, and zoom\n  in/out with the mouse wheel.\n\nhttps://user-images.githubusercontent.com/26321040/189361740-1a0876d2-9b39-49f3-a8cb-8837601b5b39.mp4\n\n- [`cube`]: A spinning cube with a parallaxed material in a basic 3d scene,\n  mouse left click to switch point of view.\n\nhttps://user-images.githubusercontent.com/26321040/189361802-3db6aa98-fa7f-4440-b5a7-20d73a36ac23.mp4\n  \n### Bugs and limitations\n\n- This doesn't implement silhouetting, so the meshes's silhouette will not\n  change with the height map\n  - As a result, height maps that are top-heavy should be favored (tree bark, bricks)\n- This doesn't implement self-shadowing, resulting in potentially surprising sharp cutoffs\n  - self-shadowing is described in the [sunblackcat] article, but bevy's lighting system requires\n    handling several light types and multiple light sources at once, which is more complex than\n    I can handle right now.\n- The height map is inverted from the more common usage\n  \n### Literature\n\nThe code is basically copied from the [sunblackcat] implementation linked\non Wikipedia.\n\nOptimization leads include:\n\n1. \u003chttps://www.diva-portal.org/smash/get/diva2:831762/FULLTEXT01.pdf\u003e\n2. \u003chttps://www.gamedevs.org/uploads/quadtree-displacement-mapping-with-height-blending.pdf\u003e\n3. \u003chttps://developer.nvidia.com/gpugems/gpugems3/part-i-geometry/chapter-4-next-generation-speedtree-rendering\u003e\n4. \u003chttps://old.reddit.com/r/GraphicsProgramming/comments/pgkogk/whatever_happened_to_quadtree_displacement_mapping/\u003e\n5. \u003chttps://www.youtube.com/watch?v=8hThP-Yni_o\u003e\n\nNote that (1) says that (2) is slower than POM, while (3) is beyond out-of-scope\nfor a small opensource crate (unless you want to pay me).\n\n### TODO\n\n- [ ] Useability\n  - [X] bevy-inspector-egui definition (~~behind compile flag~~, now derives `Reflect`)\n  - [ ] Generic over shader (should be possible to use with a\n        traditional phong shader)\n  - [ ] Conversion methods `from_standard(StandardMaterial, height_map)`\n  - [ ] Automatic `height_map` computation based on a `normal_map` if possible\n    - \u003chttps://old.reddit.com/r/gamedev/comments/fffskm/convert_normal_map_to_displacement_map/\u003e\n    - \u003chttps://forums.unrealengine.com/t/invert-normal-to-height/145496\u003e\n    - \u003chttps://houdinigubbins.wordpress.com/2019/08/09/from-normal-to-height/\u003e\n    - \u003chttps://stannum.io/blog/0IwyJ-\u003e\n    - Search keywords are a bit silly, I found that \"invert displacement map from normal map\" gave\n      satisfactory results on ddg.\n  - [ ] Implement insights from (5)\n    - The height map does't need to have the same precision as the normal map\n    - Works better when the height map doesn't have sharp differences\n      (so blur the input image)\n    - [ ] Can reduce even further the number of layers (called \"steps\" in video)\n          by accounting for distance to position.\n\n### Change log\n\n* `0.2.0`: Update bevy dependency to `0.9`\n* `0.3.0`: Update bevy dependency to `0.10`\n\n### Version Matrix\n\n| bevy | latest supporting version      |\n|------|--------|\n| 0.10 | 0.3.0 |\n| 0.9  | 0.2.0 |\n| 0.8  | 0.1.0 |\n\n\n## License\n\nEarth images in `assets/earth` are public domain and taken from Wikimedia. I edited them myself, you\nare free to re-use the edited version however you want without restrictions.\n\n- [height map]: `elevation_water.png` and `elevation_surface.png` adjust the values to highlight\n  different topological features of earth, the `normal_map.jpg` is also derived from it.\n- [albedo] (aka base color) is a scalled-down version of the 2002 Nasa blue marble earth satellite\n  view using a equirectangular projection. `metallic_roughness.png` and `base_color.jpg` are derived\n  from that image.\n- [emissive texture] is from the 2012 Nasa blue marble project. It's a night time satellite view of\n  earth.\n- An alternative higher-quality height map is available at:\n  \u003chttps://commons.wikimedia.org/wiki/File:Srtm_ramp2.world.21600x10800.jpg\u003e\n\nCopyright of code and assets go to their respective authors.\n\nOriginal code is copyright © 2022 Nicola Papale\n\nThis software is licensed under Apache 2.0.\n\n\n[parallax mapping]: https://en.wikipedia.org/wiki/Parallax_mapping\n[parallax occlusion mapping]: https://en.wikipedia.org/wiki/Parallax_occlusion_mapping\n[sunblackcat]: https://web.archive.org/web/20150419215321/http://sunandblackcat.com/tipFullView.php?l=eng\u0026topicid=28\n[height map]: https://commons.wikimedia.org/wiki/File:Earth_dry_elevation.png\n[albedo]: https://commons.wikimedia.org/wiki/File:Blue_Marble_2002_bg21600.png\n[emissive texture]: https://commons.wikimedia.org/wiki/File:Composite_map_of_the_world_2012.jpg\n[`ParallaxMaterial`]: https://docs.rs/bevy_mod_paramap/0.2.0/bevy_mod_paramap/struct.ParallaxMaterial.html\n[`algorithm`]: https://docs.rs/bevy_mod_paramap/0.2.0/bevy_mod_paramap/struct.ParallaxMaterial.html#algorithm\n[`ParallaxAlgo`]: https://docs.rs/bevy_mod_paramap/0.2.0/bevy_mod_paramap/enum.ParallaxAlgo.html\n[`cube`]: https://github.com/nicopap/bevy_mod_paramap/blob/main/examples/cube.rs\n[`earth3d`]: https://github.com/nicopap/bevy_mod_paramap/blob/main/examples/earth3d.rs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicopap%2Fbevy_mod_paramap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicopap%2Fbevy_mod_paramap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicopap%2Fbevy_mod_paramap/lists"}