[ { "path": ".gitattributes", "content": "*.tif filter=lfs diff=lfs merge=lfs -text\n" }, { "path": ".gitignore", "content": ".idea\nCargo.lock\ntarget\nassets/**/data/*\nassets/**/config.tc\nassets/terrains/spherical/source/height/200m.tif" }, { "path": "Cargo.toml", "content": "[package]\nname = \"bevy_terrain\"\ndescription = \"Terrain Rendering for the Bevy Engine.\"\nversion = \"0.1.0-dev\"\nlicense = \"MIT OR Apache-2.0\"\nedition = \"2021\"\ncategories = [\"game-engines\", \"rendering\", \"graphics\"]\nkeywords = [\"gamedev\", \"graphics\", \"bevy\", \"terrain\"]\nexclude = [\"assets/*\"]\nreadme = \"README.md\"\nauthors = [\"Kurt Kühnert \"]\nrepository = \"https://github.com/kurtkuehnert/bevy_terrain\"\n\n[features]\nhigh_precision = [\"dep:big_space\"]\n\n[dependencies]\nbevy = \"0.14.0\" #{ git=\"https://github.com/bevyengine/bevy/\", branch=\"main\" }\nndarray = \"0.15\"\nitertools = \"0.12\"\nimage = \"0.25\"\ntiff = \"0.9\"\nlru = \"0.12\"\nbitflags = \"2.4\"\nbytemuck = \"1.14\"\nanyhow = \"1.0\"\nbincode = \"2.0.0-rc.3\"\nasync-channel = \"2.1\"\nbig_space = { version = \"0.7\", optional = true }\n\n[[example]]\nname = \"preprocess_planar\"\npath = \"examples/preprocess_planar.rs\"\nrequired-features = [\"bevy/embedded_watcher\"]\n\n[package.metadata.example.preprocess_planar]\nname = \"Preprocess Planar\"\ndescription = \"Preprocesses the terrain data for the planar examples.\"\n\n[[example]]\nname = \"minimal\"\npath = \"examples/minimal.rs\"\nrequired-features = [\"bevy/embedded_watcher\"]\n\n[package.metadata.example.minial]\nname = \"Minimal\"\ndescription = \"Renders a basic flat terrain with only the base attachment.\"\n\n[[example]]\nname = \"planar\"\npath = \"examples/planar.rs\"\nrequired-features = [\"high_precision\", \"bevy/embedded_watcher\"]\n\n[package.metadata.example.planar]\nname = \"Planar Advanced\"\ndescription = \"Renders a flat terrain with the base attachment and an albedo texture, using a custom shader.\"\n\n[[example]]\nname = \"preprocess_spherical\"\npath = \"examples/preprocess_spherical.rs\"\nrequired-features = [\"bevy/embedded_watcher\"]\n\n[package.metadata.example.preprocess_spherical]\nname = \"Preprocess Spherical\"\ndescription = \"Preprocesses the terrain data for the spherical examples.\"\n\n[[example]]\nname = \"spherical\"\npath = \"examples/spherical.rs\"\nrequired-features = [\"high_precision\", \"bevy/embedded_watcher\"]\n\n[package.metadata.example.spherical]\nname = \"Spherical\"\ndescription = \"Renders a spherical terrain using a custom shader.\"\n\n" }, { "path": "LICENSE-APACHE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n" }, { "path": "LICENSE-MIT", "content": "MIT License\n\nCopyright (c) 2023 Kurt Kühnert\nCopyright (c) 2023 Argeo\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE." }, { "path": "README.md", "content": "# Bevy Terrain\n\n![GitHub](https://img.shields.io/github/license/Ku95/bevy_terrain)\n![Crates.io](https://img.shields.io/crates/v/bevy_terrain)\n![docs.rs](https://img.shields.io/docsrs/bevy_terrain)\n![Discord](https://img.shields.io/discord/999221999517843456?label=discord)\n\nBevy Terrain is a plugin for rendering terrains with the Bevy game engine.\n\n![](https://user-images.githubusercontent.com/51823519/202845032-0537e929-b13c-410b-8072-4c5b5df9830d.png)\n(Data Source: Federal Office of Topography, [©swisstopo](https://www.swisstopo.admin.ch/en/home.html))\n\n**Warning:** This plugin is still in early development, so expect the API to change and possibly break you existing\ncode.\n\nBevy terrain was developed as part of my [bachelor thesis](https://github.com/kurtkuehnert/terrain_renderer) on the\ntopic of large-scale terrain rendering.\nNow that this project is finished I am planning on adding more features related to game development and rendering\nvirtual worlds.\nIf you would like to help me build an extensive open-source terrain rendering library for the Bevy game engine, feel\nfree to contribute to the project.\nAlso, join the Bevy Terrain [Discord server](https://discord.gg/7mtZWEpA82) for help, feedback, or to discuss feature\nideas.\n\n## Examples\n\nCurrently, there are two examples.\n\nThe basic one showcases the different debug views of the terrain. See controls down below.\n\nThe advanced one showcases how to use the Bevy material system for texturing,\nas well as how to add additional terrain attachments.\nUse the `A` Key to toggle between the custom material and the albedo attachment.\n\nBefore running the examples you have to preprocess the terrain data this may take a while.\nOnce the data is preprocessed you can disable it by commenting out the preprocess line.\n\n## Documentation\n\nThe `docs` folder contains a\nhigh-level [implementation overview](https://github.com/kurtkuehnert/bevy_terrain/blob/main/docs/implementation.md),\nas well as, the [development status](https://github.com/kurtkuehnert/bevy_terrain/blob/main/docs/development.md),\nenumerating the features that I am planning on implementing next, of the project.\nIf you would like to contribute to the project this is a good place to start. Simply pick an issue/feature and discuss\nthe details with me on Discord or GitHub.\nI would also recommend you to take a look at\nmy [thesis](https://github.com/kurtkuehnert/terrain_renderer/blob/main/Thesis.pdf).\nThere I present the basics of terrain rendering (chapter 2), common approaches (chapter 3) and a detailed explanation of\nmethod used by `bevy_terrain` (chapter 4).\n\n## Debug Controls\n\nThese are the debug controls of the plugin.\nUse them to fly over the terrain, experiment with the quality settings and enter the different debug views.\n\n- `T` - toggle camera movement\n- move the mouse to look around\n- press the arrow keys to move the camera horizontally\n- use `PageUp` and `PageDown` to move the camera vertically\n- use `Home` and `End` to increase/decrease the camera's movement speed\n\n- `W` - toggle wireframe view\n- `P` - toggle tile view\n- `L` - toggle lod view\n- `U` - toggle uv view\n- `C` - toggle tile view\n- `D` - toggle mesh morph\n- `A` - toggle albedo\n- `B` - toggle base color black / white\n- `S` - toggle lighting\n- `G` - toggle filtering bilinear / trilinear + anisotropic\n- `F` - freeze frustum culling\n- `H` - decrease tile scale\n- `J` - increase tile scale\n- `N` - decrease grid size\n- `E` - increase grid size\n- `I` - decrease view distance\n- `O` - increase view distance\n\n\n\n## Attribution\n\nThe planar terrain dataset is generated using the free version of the Gaia Terrain Generator.\nThe spherical terrain example dataset is a reprojected version of the GEBCO_2023 Grid dataset.\n\nGEBCO Compilation Group (2023) GEBCO 2023 Grid (doi:10.5285/f98b053b-0cbc-6c23-e053-6c86abc0af7b)\n\n## License\n\nBevy Terrain source code (this excludes the datasets in the assets directory) is dual-licensed under either\n\n* MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)\n* Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)\n\nat your option.\n" }, { "path": "assets/shaders/planar.wgsl", "content": "#import bevy_terrain::types::AtlasTile\n#import bevy_terrain::attachments::{sample_attachment0 as sample_height, sample_normal, sample_attachment1 as sample_albedo}\n#import bevy_terrain::fragment::{FragmentInput, FragmentOutput, fragment_info, fragment_output, fragment_debug}\n#import bevy_terrain::functions::lookup_tile\n#import bevy_pbr::pbr_types::{PbrInput, pbr_input_new}\n\n@group(3) @binding(0)\nvar gradient: texture_1d;\n@group(3) @binding(1)\nvar gradient_sampler: sampler;\n\nfn sample_color(tile: AtlasTile) -> vec4 {\n#ifdef ALBEDO\n return sample_albedo(tile);\n#else\n let height = sample_height(tile).x;\n\n return textureSampleLevel(gradient, gradient_sampler, pow(height, 0.9), 0.0);\n#endif\n}\n\n@fragment\nfn fragment(input: FragmentInput) -> FragmentOutput {\n var info = fragment_info(input);\n\n let tile = lookup_tile(info.coordinate, info.blend, 0u);\n var color = sample_color(tile);\n var normal = sample_normal(tile, info.world_normal);\n\n if (info.blend.ratio > 0.0) {\n let tile2 = lookup_tile(info.coordinate, info.blend, 1u);\n color = mix(color, sample_color(tile2), info.blend.ratio);\n normal = mix(normal, sample_normal(tile2, info.world_normal), info.blend.ratio);\n }\n\n var output: FragmentOutput;\n fragment_output(&info, &output, color, normal);\n fragment_debug(&info, &output, tile, normal);\n return output;\n}\n" }, { "path": "assets/shaders/spherical.wgsl", "content": "#import bevy_terrain::types::{AtlasTile}\n#import bevy_terrain::bindings::config\n#import bevy_terrain::attachments::{sample_height, sample_normal}\n#import bevy_terrain::fragment::{FragmentInput, FragmentOutput, fragment_info, fragment_output, fragment_debug}\n#import bevy_terrain::functions::lookup_tile\n#import bevy_pbr::pbr_types::{PbrInput, pbr_input_new}\n#import bevy_pbr::pbr_functions::{calculate_view, apply_pbr_lighting}\n\n\n@group(3) @binding(0)\nvar gradient: texture_1d;\n@group(3) @binding(1)\nvar gradient_sampler: sampler;\n\nfn sample_color(tile: AtlasTile) -> vec4 {\n let height = sample_height(tile);\n\n var color: vec4;\n\n if (height < 0.0) {\n color = textureSampleLevel(gradient, gradient_sampler, mix(0.0, 0.075, pow(height / config.min_height, 0.25)), 0.0);\n }\n else {\n color = textureSampleLevel(gradient, gradient_sampler, mix(0.09, 1.0, pow(height / config.max_height * 2.0, 1.0)), 0.0);\n }\n\n return color;\n}\n\n@fragment\nfn fragment(input: FragmentInput) -> FragmentOutput {\n var info = fragment_info(input);\n\n let tile = lookup_tile(info.coordinate, info.blend, 0u);\n var color = sample_color(tile);\n var normal = sample_normal(tile, info.world_normal);\n\n if (info.blend.ratio > 0.0) {\n let tile2 = lookup_tile(info.coordinate, info.blend, 1u);\n color = mix(color, sample_color(tile2), info.blend.ratio);\n normal = mix(normal, sample_normal(tile2, info.world_normal), info.blend.ratio);\n }\n\n var output: FragmentOutput;\n fragment_output(&info, &output, color, normal);\n fragment_debug(&info, &output, tile, normal);\n return output;\n}\n" }, { "path": "docs/development.md", "content": "# Development Status Bevy Terrain\n\nThis document assesses the current status of the `bevy_terrain` plugin.\nI built this plugin as part of my bachelor thesis, which focused on rendering large-scale terrains.\nThe thesis and its project can be found [here](https://github.com/kurtkuehnert/terrain_renderer).\n\nFor that, I set out to solve two key problems of terrain rendering. \nFor one, I developed the Uniform Distance-Dependent Level of Detail (UDLOD) algorithm to represent the terrain geometry, and for another, \nI came up with the Chunked Clipmap data structure used to represent the terrain data. \nBoth are implemented as part of bevy terrain and work quite well for rendering large-scale terrains.\n\nNow that I have finished my thesis I would like to continue working on this project and extend its capabilities. \nThe topic of terrain rendering is vast, and thus I can not work on all the stuff at once.\nIn the following, I will list a couple of features that I would like to integrate into this crate in the future. \nI will probably not have the time to implement all of them by myself, so if you are interested please get in touch, and let us work on them together. \nAdditionally, there are still plenty of improvements, bug fixes, and optimizations to be completed on the already existing implementation.\n\n## Features\n\n- Procedural Texturing\n- Shadow Rendering\n- Real-Time Editing\n- Collision\n- Path-Finding\n- Spherical Terrain\n\n### Procedural Texturing\n\nProbably the biggest missing puzzle piece of this plugin is support for procedural texturing using splat maps or something similar. \nCurrently, texturing has to be implemented manually in the terrain shader (see the advanced example for reference). \nI would like to support this use case in a more integrated manner in the future. Unfortunately, \nI am not familiar with the terrain texturing systems of other engines (e.g. Unity, Unreal, Godot) \nor have any experience texturing and building my own terrains. \nI would greatly appreciate it if anyone can share some requirements for this area of terrain rendering. \nAlso, a prototype of a custom texturing system would be a great resource to develop further ideas.\n\n### Shadow Rendering\n\nAnother important capability that is currently missing is the support for large-scale shadow rendering. \nThis would be probably implemented using cascading shadow maps or a similar method.\nCurrently, Bevy itself does not implement a system we could use for this yet. \nRegardless, I think reusing Bevy’s implementation would be the best choice in the future.\n\n### Real-Time Editing\n\nOne of the most interesting problems that need to be solved before `bevy_terrain` can be used for any serious project is the editing of the terrain data in real time. \nThis is not only important for sculpting the terrain of your game, but also for texturing, vegetation placement, etc.\nThis is going to be my next focus area and I would like to discuss designs and additional requirements with anyone interested.\n\n### Collision\n\nSame as for shadow rendering, Bevy does not have a built-in physics engine yet. For now, the de-facto standard is the rapier physics engine. \nIntegrating the collision of the terrain with rapier would enable many types of games and is a commonly requested feature.\n\n### Path-Finding\n\nSimilar to collision, path-finding is essential for most games. I have not investigated this field at all yet, but I am always interested in your ideas.\n\n### Spherical Terrain\n\nI think that with a little design work the current two-dimensional terrain rendering method could be extended to the spherical terrain.\nHowever, I am unsure how much of the existing code could be extended and reused. Maybe planet rendering would require its entirely separate crate.\n" }, { "path": "docs/implementation.md", "content": "# Implementation Overview Bevy Terrain\n\nThis document serves as a general overview of the implementation of the `bevy_terrain` plugin.\n\nCurrently, this crate provides two fundamental capabilities.\nFor one, the UDLOD algorithm approximates the terrain geometry, and for another, the Chunked Clipmap stores the terrain\ndata in a convenient and randomly accessible data structure.\n\nBoth are described in detail in\nmy [bachelor thesis]([https://github.com/kurtkuehnert/terrain_renderer/blob/main/Thesis.pdf](https://github.com/kurtkuehnert/terrain_renderer/blob/main/Thesis.pdf)).\nTo understand the implementation of this crate and the reasons behind some design decisions, I recommend that you read\nat least the entire chapter 4.\nIf you are unfamiliar with terrain rendering in general, taking a look at chapter 2 will prove beneficial as well.\n\nIn the following, I will now explain how both of these systems are currently implemented, what limitations they possess,\nand how they should work in the future.\nFurthermore, I have listed a couple of todos outlining the essence of these issues.\nIf any of them sound interesting to you, and you would like to work on them, please get in touch with me, so we can\ndiscuss solutions.\nThese are certainly not all problems of the current implementation, so if you notice anything else, please let me know,\nso I can add it here.\n\n## Terrain Geometry\n\n### Ideal\n\nIdeally, we would like to represent the terrain geometry without any error according to our source data. Unfortunately,\nrendering each data point as a vertex is not scalable, nor efficient.\n\n### Reality\n\nThat is why we need a sophisticated level of detail (LOD) algorithm that minimizes the error introduced by its\napproximation of the geometry.\n\n### Solution\n\nOne such solution is the Uniform Distance-Dependent Level of Detail (UDLOD) algorithm that I have developed as part of\nmy thesis (for a detailed explanation read section 4.4).\nIt divides the terrain into numerous small tiles in parallel on the GPU. They are then rendered using a single indirect\ndraw call and morphed together (in the vertex shader) to form a continuous surface with an approximately uniform\ntessellation in screen space.\n\n### Issues\n\nFor any LOD algorithm, an appropriate crack-avoiding and morphing strategy are important to eliminate and reduce visual\ndiscrepancies as much as possible.\nUDLOD uses a slightly modified version of the CDLOD morphing scheme.\n\nThe UDLOD algorithm can be used to tessellate procedural ground details like rocks or cobblestones as well.\nTherefore, simply increase the tile_tree depth using the `additional_refinement` parameter.\n\nEven though the tessellation produced by UDLOD is somewhat uniform with respect to the distance, it does not take\nfactors like the terrain's roughness and the viewing angle into account.\nGenerally, the current UDLOD algorithm tiers to cover the worst-case terrain roughness like many other algorithms (\nGeoMipmap, GeoClipmap, PGM, CDLOD, FarCry5).\nI believe that we can still develop more efficient LOD algorithms that scale favorably for large-scale terrains in the\nfuture.\n\nThe culling is currently pretty bare-bones.\nWe could probably implement most of the techniques researched by the Far Cry 5 terrain renderer as well.\n\nCurrently, the prepass is pretty inefficient, because the shader occupancy is very low (the prepass is still plenty\nfast, but could be improved).\nI think that this could be resolved by using the atomic operations more cleverly and reducing the shader dispatches in\ngeneral.\nIn the past, I have tried doing all the work in a single pass.\nUnfortunately, that did not work, but maybe someone can figure out a better solution.\n\nThe frustum culling uses a 2D min-max height data attachment to approximate the bounding volumes of each tile correctly.\nThis is currently stored with the same resolution as the source height data, but only a fraction of this resolution is\nactually required.\n\n### Todo\n\n- [x] come up with a smooth morphing strategy that solves the geometry crack problem as well\n- [x] implement bounding box frustum culling\n- [x] further refine the geometry for procedural details (rocks, cobblestone)\n- [ ] explore different LOD algorithms (maybe apply the clipmap idea to CBTs?)\n- [ ] try incorporating a screen space error metric, local terrain roughness, or the viewing angle\n- [ ] implement more advanced culling solutions (occlusion, backface)\n- [ ] try reducing the compute shader dispatches in the prepass phase\n- [ ] store min-max height data, required by frustum culling, at a way lower resolution\n- [ ] experiment with hardware tessellation or mesh shaders\n\n## Terrain Data\n\n### Ideal\n\nIdeally, we would like to store any desired information at any desired resolution across the terrain’s surface.\nFor example, a terrain could require a heightmap with a resolution of 0.5m, an albedo map with a resolution of 0.2m, and\na vegetation map (for placing trees and bushes) with a resolution of 1m.\nEach of these three different kinds of terrain data are called terrain attachments.\nThis terrain data should be available in any system and shader of our application. Additionally, we would like to access\nthe data at any position and sample a value with distant-dependent accuracy.\nFinally, some use cases require the ability to sample some attachments like the albedo or splat data trilinearly and\nanisotropically to mitigate aliasing artifacts.\n\n### Reality\n\nBecause we are using height-map-based terrain these attachments should be stored as large two-dimensional textures.\nHowever, due to the size of most landscapes, using a single texture would quickly use up all of our video memory.\nThat is why we need to partition and adjust the loaded data according to our view.\nAdditionally, it is important that we can share this terrain data efficiently between multiple views for use cases like\nsplit-screen or shadow rendering.\n\n### Solution\n\nTo solve this, I have developed the chunked clipmap data structure (if you are unfamiliar with the concept, I encourage\nyou to read section 4.5 of my thesis).\nIt divides the entire terrain data into one large tile_tree, covering the entire terrain.\nThis requires that all terrain data has to be preprocessed into small square textures: the tiles of the tile_tree.\nEach tile possesses one texture per attachment. To allow for different resolutions of the attachments (e.g. the\nheight data should be twice as accurate as our splat map), the size of these textures has to be different as well.\nFollowing the same example, this would mean that the height textures would have a size of 100x100 and the splat textures\na size of 50x50 pixels.\n\n### Issues\n\nBecause of our compound representation of the terrain data, consisting of many small textures, some problems arise\nduring texture filtering.\nThe biggest issue is that adjacent tiles do not line up perfectly due to missing texture information at the border.\nThis causes noticeable texture seams between adjacent tiles.\nTo remedy this issue we have to duplicate the border data between adjacent tiles.\nThis complicates our preprocessing but results in a completely seamless terrain data representation.\n\nFor trilinear filtering, we additionally require mipmap information.\nCurrently, bevy does not support mipmap generation.\nThat is why I have implemented a simple mipmap creation function, which is executed after the tile textures have\nbeen loaded. Unfortunately, my simple approach only works on textures with a side length equal to a power of two (e.g.\n256x256, 512x512).\nThis needlessly limits the resolutions of our terrain data.\nIn the future, I would like to generate the mipmaps for any texture size.\n\nAs mentioned above the terrain data has to be loaded depending on our current view position.\nCurrently, I load all tiles inside the `load_distance` around the viewer.\nThere is no prioritization or load balancing. I would like to explore different loading strategies (e.g. distance only,\nview frustum based, etc.) to enable use cases like streaming data from a web server.\nFor that, the strategy would have to minimize the loading requests while maximizing the visual quality.\nWhen streaming from disk this wasn't a problem yet.\n\nAdditionally, the plugin panics if the tile atlas is out of indices (i.e. the maximum amount of tiles is\nloaded).\nThis is unacceptable in production use.\nHere we would have to come up with a strategy of prioritizing which tiles to keep and which ones to discard in\norder to accommodate more important ones.\n\nThe tile loading code itself is currently pretty inefficient.\nDue to the nature of the bevy image abstraction, all textures are duplicated multiple times.\nHopefully in the near future, once the asset processing has been reworked, it will be easier to express loading parts of\nan array texture directly.\n\nTo divide the terrain into the numerous tile textures I use a 3-step preprocessing algorithm.\nThis is implemented pretty inefficiently.\nIf you are interested in optimizing data transformation code, this should be the task for you :D.\n\nTo save space the terrain data is compressed using common image formats, when it is stored on the hard-drive.\nTo unfortunately the encoding of PNGs is quite slow.\nThat is why I came up with the [DTM image format](https://github.com/kurtkuehnert/dtm).\nIt uses a sequential compression technique similar to the QOI format.\nDTM works quite well for the shallow terrain I used for testing, but is not ideal for the steep and hilly terrains used\nin most games.\nThere are probably significant gains to be had in this area.\n\nAnother huge challenge regarding the terrain data is its modification in real-time.\nWorkflows like sculpting, texturing, etc. do require the ability to update the terrain data in a visual manner.\nThis topic is vast and will require extensive investigation before we can settle on a final design.\nIf you have experience/ideas please let me know.\n\n### Todo\n\n- [x] duplicate border information to eliminate texture seams\n- [x] generate mipmaps to enable trilinear filtering\n- [ ] Incorporate better mipmap generation for any texture size.\n- [ ] different loading strategies\n- [ ] handle tile atlas out of indices\n- [ ] improve loading to tile atlas (i.e. loading layers of an array texture), remove excessive\n duplication/copying\n- [ ] improve the preprocessing with caching, GPU acceleration, etc.\n- [ ] explore the usage of more efficient image formats\n- [ ] investigate real-time modification\n" }, { "path": "examples/minimal.rs", "content": "use bevy::math::DVec3;\nuse bevy::prelude::*;\nuse bevy_terrain::prelude::*;\n\nconst PATH: &str = \"terrains/planar\";\nconst TERRAIN_SIZE: f64 = 1000.0;\nconst HEIGHT: f32 = 250.0;\nconst TEXTURE_SIZE: u32 = 512;\nconst LOD_COUNT: u32 = 4;\n\nfn main() {\n App::new()\n .add_plugins((\n DefaultPlugins,\n TerrainPlugin,\n TerrainMaterialPlugin::::default(),\n TerrainDebugPlugin,\n ))\n .add_systems(Startup, setup)\n .run();\n}\n\nfn setup(\n mut commands: Commands,\n mut materials: ResMut>,\n mut tile_trees: ResMut>,\n mut meshes: ResMut>,\n) {\n // Configure all the important properties of the terrain, as well as its attachments.\n let config = TerrainConfig {\n lod_count: LOD_COUNT,\n model: TerrainModel::planar(DVec3::new(0.0, -100.0, 0.0), TERRAIN_SIZE, 0.0, HEIGHT),\n path: PATH.to_string(),\n ..default()\n }\n .add_attachment(AttachmentConfig {\n name: \"height\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n mip_level_count: 4,\n format: AttachmentFormat::R16,\n });\n\n // Configure the quality settings of the terrain view. Adapt the settings to your liking.\n let view_config = TerrainViewConfig::default();\n\n let tile_atlas = TileAtlas::new(&config);\n let tile_tree = TileTree::new(&tile_atlas, &view_config);\n\n let terrain = commands\n .spawn((\n TerrainBundle::new(tile_atlas),\n materials.add(DebugTerrainMaterial::default()),\n ))\n .id();\n\n let view = commands.spawn(DebugCameraBundle::default()).id();\n\n tile_trees.insert((terrain, view), tile_tree);\n\n commands.spawn(PbrBundle {\n mesh: meshes.add(Cuboid::from_length(10.0)),\n transform: Transform::from_translation(Vec3::new(\n TERRAIN_SIZE as f32 / 2.0,\n 100.0,\n TERRAIN_SIZE as f32 / 2.0,\n )),\n ..default()\n });\n}\n" }, { "path": "examples/planar.rs", "content": "use bevy::math::DVec3;\nuse bevy::{prelude::*, reflect::TypePath, render::render_resource::*};\nuse bevy_terrain::prelude::*;\n\nconst PATH: &str = \"terrains/planar\";\nconst TERRAIN_SIZE: f64 = 2000.0;\nconst HEIGHT: f32 = 500.0;\nconst TEXTURE_SIZE: u32 = 512;\nconst LOD_COUNT: u32 = 8;\n\n#[derive(Asset, AsBindGroup, TypePath, Clone)]\npub struct TerrainMaterial {\n #[texture(0, dimension = \"1d\")]\n #[sampler(1)]\n gradient: Handle,\n}\n\nimpl Material for TerrainMaterial {\n fn fragment_shader() -> ShaderRef {\n \"shaders/planar.wgsl\".into()\n }\n}\n\nfn main() {\n App::new()\n .add_plugins((\n DefaultPlugins.build().disable::(),\n TerrainPlugin,\n TerrainDebugPlugin, // enable debug settings and controls\n TerrainMaterialPlugin::::default(),\n ))\n .add_systems(Startup, setup)\n .run();\n}\n\nfn setup(\n mut commands: Commands,\n mut images: ResMut,\n mut materials: ResMut>,\n mut tile_trees: ResMut>,\n asset_server: Res,\n) {\n let gradient = asset_server.load(\"textures/gradient2.png\");\n images.load_image(\n &gradient,\n TextureDimension::D1,\n TextureFormat::Rgba8UnormSrgb,\n );\n\n // Configure all the important properties of the terrain, as well as its attachments.\n let config = TerrainConfig {\n lod_count: LOD_COUNT,\n model: TerrainModel::planar(DVec3::new(0.0, -100.0, 0.0), TERRAIN_SIZE, 0.0, HEIGHT),\n path: PATH.to_string(),\n ..default()\n }\n .add_attachment(AttachmentConfig {\n name: \"height\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n mip_level_count: 4,\n format: AttachmentFormat::R16,\n })\n .add_attachment(AttachmentConfig {\n name: \"albedo\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n mip_level_count: 4,\n format: AttachmentFormat::Rgba8,\n });\n\n // Configure the quality settings of the terrain view. Adapt the settings to your liking.\n let view_config = TerrainViewConfig::default();\n\n let tile_atlas = TileAtlas::new(&config);\n let tile_tree = TileTree::new(&tile_atlas, &view_config);\n\n commands.spawn_big_space(ReferenceFrame::default(), |root| {\n let frame = root.frame().clone();\n\n let terrain = root\n .spawn_spatial((\n TerrainBundle::new(tile_atlas, &frame),\n materials.add(TerrainMaterial { gradient }),\n ))\n .id();\n\n let view = root.spawn_spatial(DebugCameraBundle::default()).id();\n\n tile_trees.insert((terrain, view), tile_tree);\n });\n}\n" }, { "path": "examples/preprocess_planar.rs", "content": "use bevy::prelude::*;\nuse bevy_terrain::prelude::*;\n\nconst PATH: &str = \"terrains/planar\";\nconst TEXTURE_SIZE: u32 = 512;\nconst LOD_COUNT: u32 = 4;\n\nfn main() {\n App::new()\n .add_plugins((DefaultPlugins, TerrainPlugin, TerrainPreprocessPlugin))\n .add_systems(Startup, setup)\n .run();\n}\n\nfn setup(mut commands: Commands, asset_server: Res) {\n let config = TerrainConfig {\n lod_count: LOD_COUNT,\n path: PATH.to_string(),\n ..default()\n }\n .add_attachment(AttachmentConfig {\n name: \"height\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n format: AttachmentFormat::R16,\n ..default()\n })\n .add_attachment(AttachmentConfig {\n name: \"albedo\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n format: AttachmentFormat::Rgba8,\n ..default()\n });\n\n let mut tile_atlas = TileAtlas::new(&config);\n\n let preprocessor = Preprocessor::new()\n .clear_attachment(0, &mut tile_atlas)\n .clear_attachment(1, &mut tile_atlas)\n .preprocess_tile(\n PreprocessDataset {\n attachment_index: 0,\n path: format!(\"{PATH}/source/height.png\"),\n lod_range: 0..LOD_COUNT,\n ..default()\n },\n &asset_server,\n &mut tile_atlas,\n )\n .preprocess_tile(\n PreprocessDataset {\n attachment_index: 1,\n path: format!(\"{PATH}/source/albedo.png\"),\n lod_range: 0..LOD_COUNT,\n ..default()\n },\n &asset_server,\n &mut tile_atlas,\n );\n\n commands.spawn((tile_atlas, preprocessor));\n}\n" }, { "path": "examples/preprocess_spherical.rs", "content": "use bevy::prelude::*;\nuse bevy_terrain::prelude::*;\n\nconst PATH: &str = \"terrains/spherical\";\nconst TEXTURE_SIZE: u32 = 512;\nconst LOD_COUNT: u32 = 5;\n\nfn main() {\n App::new()\n .add_plugins((\n DefaultPlugins.build().disable::(),\n TerrainPlugin,\n TerrainPreprocessPlugin,\n ))\n .add_systems(Startup, setup)\n .run();\n}\n\nfn setup(mut commands: Commands, asset_server: Res) {\n let config = TerrainConfig {\n lod_count: LOD_COUNT,\n path: PATH.to_string(),\n atlas_size: 2048,\n ..default()\n }\n .add_attachment(AttachmentConfig {\n name: \"height\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n format: AttachmentFormat::R16,\n ..default()\n });\n\n let mut tile_atlas = TileAtlas::new(&config);\n\n let preprocessor = Preprocessor::new()\n .clear_attachment(0, &mut tile_atlas)\n .preprocess_spherical(\n SphericalDataset {\n attachment_index: 0,\n paths: (0..6)\n .map(|side| format!(\"{PATH}/source/height/face{side}.tif\"))\n .collect(),\n lod_range: 0..LOD_COUNT,\n },\n &asset_server,\n &mut tile_atlas,\n );\n\n commands.spawn((tile_atlas, preprocessor));\n}\n" }, { "path": "examples/spherical.rs", "content": "use bevy::{math::DVec3, prelude::*, reflect::TypePath, render::render_resource::*};\nuse bevy_terrain::prelude::*;\n\nconst PATH: &str = \"terrains/spherical\";\nconst RADIUS: f64 = 6371000.0;\nconst MAJOR_AXES: f64 = 6378137.0;\nconst MINOR_AXES: f64 = 6356752.314245;\nconst MIN_HEIGHT: f32 = -12000.0;\nconst MAX_HEIGHT: f32 = 9000.0;\nconst TEXTURE_SIZE: u32 = 512;\nconst LOD_COUNT: u32 = 16;\n\n#[derive(Asset, AsBindGroup, TypePath, Clone)]\npub struct TerrainMaterial {\n #[texture(0, dimension = \"1d\")]\n #[sampler(1)]\n gradient: Handle,\n}\n\nimpl Material for TerrainMaterial {\n fn fragment_shader() -> ShaderRef {\n \"shaders/spherical.wgsl\".into()\n }\n}\n\nfn main() {\n App::new()\n .add_plugins((\n DefaultPlugins.build().disable::(),\n TerrainPlugin,\n TerrainMaterialPlugin::::default(),\n TerrainDebugPlugin, // enable debug settings and controls\n ))\n // .insert_resource(ClearColor(Color::WHITE))\n .add_systems(Startup, setup)\n .run();\n}\n\nfn setup(\n mut commands: Commands,\n mut images: ResMut,\n mut meshes: ResMut>,\n mut materials: ResMut>,\n mut tile_trees: ResMut>,\n asset_server: Res,\n) {\n let gradient = asset_server.load(\"textures/gradient.png\");\n images.load_image(\n &gradient,\n TextureDimension::D1,\n TextureFormat::Rgba8UnormSrgb,\n );\n\n // Configure all the important properties of the terrain, as well as its attachments.\n let config = TerrainConfig {\n lod_count: LOD_COUNT,\n model: TerrainModel::ellipsoid(DVec3::ZERO, MAJOR_AXES, MINOR_AXES, MIN_HEIGHT, MAX_HEIGHT),\n // model: TerrainModel::ellipsoid(\n // DVec3::ZERO,\n // 6378137.0,\n // 6378137.0 * 0.5,\n // MIN_HEIGHT,\n // MAX_HEIGHT,\n // ),\n // model: TerrainModel::sphere(DVec3::ZERO, RADIUS),\n path: PATH.to_string(),\n ..default()\n }\n .add_attachment(AttachmentConfig {\n name: \"height\".to_string(),\n texture_size: TEXTURE_SIZE,\n border_size: 2,\n mip_level_count: 4,\n format: AttachmentFormat::R16,\n });\n\n // Configure the quality settings of the terrain view. Adapt the settings to your liking.\n let view_config = TerrainViewConfig::default();\n\n let tile_atlas = TileAtlas::new(&config);\n let tile_tree = TileTree::new(&tile_atlas, &view_config);\n\n commands.spawn_big_space(ReferenceFrame::default(), |root| {\n let frame = root.frame().clone();\n\n let terrain = root\n .spawn_spatial((\n TerrainBundle::new(tile_atlas, &frame),\n materials.add(TerrainMaterial {\n gradient: gradient.clone(),\n }),\n ))\n .id();\n\n let view = root\n .spawn_spatial(DebugCameraBundle::new(\n -DVec3::X * RADIUS * 3.0,\n RADIUS,\n &frame,\n ))\n .id();\n\n tile_trees.insert((terrain, view), tile_tree);\n\n let sun_position = DVec3::new(-1.0, 1.0, -1.0) * RADIUS * 10.0;\n let (sun_cell, sun_translation) = frame.translation_to_grid(sun_position);\n\n root.spawn_spatial((\n PbrBundle {\n mesh: meshes.add(Sphere::new(RADIUS as f32 * 2.0).mesh().build()),\n transform: Transform::from_translation(sun_translation),\n ..default()\n },\n sun_cell,\n ));\n\n root.spawn_spatial(PbrBundle {\n mesh: meshes.add(Cuboid::from_length(RADIUS as f32 * 0.1)),\n ..default()\n });\n });\n}\n" }, { "path": "src/big_space.rs", "content": "pub use big_space::{BigSpaceCommands, FloatingOrigin};\n\npub type GridPrecision = i32;\n\npub type BigSpacePlugin = big_space::BigSpacePlugin;\npub type ReferenceFrame = big_space::reference_frame::ReferenceFrame;\npub type ReferenceFrames<'w, 's> =\n big_space::reference_frame::local_origin::ReferenceFrames<'w, 's, GridPrecision>;\npub type GridCell = big_space::GridCell;\npub type GridTransform = big_space::world_query::GridTransform;\npub type GridTransformReadOnly = big_space::world_query::GridTransformReadOnly;\npub type GridTransformOwned = big_space::world_query::GridTransformOwned;\npub type GridTransformItem<'w> = big_space::world_query::GridTransformItem<'w, GridPrecision>;\n" }, { "path": "src/debug/camera.rs", "content": "#[cfg(feature = \"high_precision\")]\nuse crate::big_space::{\n FloatingOrigin, GridCell, GridTransform, GridTransformItem, ReferenceFrame, ReferenceFrames,\n};\n\nuse bevy::{input::mouse::MouseMotion, math::DVec3, prelude::*};\n\n#[derive(Bundle)]\npub struct DebugCameraBundle {\n pub camera: Camera3dBundle,\n pub controller: DebugCameraController,\n #[cfg(feature = \"high_precision\")]\n pub cell: GridCell,\n #[cfg(feature = \"high_precision\")]\n pub origin: FloatingOrigin,\n}\n\nimpl Default for DebugCameraBundle {\n fn default() -> Self {\n Self {\n camera: default(),\n controller: default(),\n #[cfg(feature = \"high_precision\")]\n cell: default(),\n #[cfg(feature = \"high_precision\")]\n origin: FloatingOrigin,\n }\n }\n}\n\nimpl DebugCameraBundle {\n #[cfg(feature = \"high_precision\")]\n pub fn new(position: DVec3, speed: f64, frame: &ReferenceFrame) -> Self {\n let (cell, translation) = frame.translation_to_grid(position);\n\n Self {\n camera: Camera3dBundle {\n transform: Transform::from_translation(translation).looking_to(Vec3::X, Vec3::Y),\n projection: PerspectiveProjection {\n near: 0.000001,\n ..default()\n }\n .into(),\n ..default()\n },\n cell,\n controller: DebugCameraController {\n translation_speed: speed,\n ..default()\n },\n ..default()\n }\n }\n\n #[cfg(not(feature = \"high_precision\"))]\n pub fn new(position: Vec3, speed: f64) -> Self {\n Self {\n camera: Camera3dBundle {\n transform: Transform::from_translation(position).looking_to(Vec3::X, Vec3::Y),\n projection: PerspectiveProjection {\n near: 0.000001,\n ..default()\n }\n .into(),\n ..default()\n },\n controller: DebugCameraController {\n translation_speed: speed,\n ..default()\n },\n ..default()\n }\n }\n}\n\n#[derive(Clone, Debug, Reflect, Component)]\npub struct DebugCameraController {\n pub enabled: bool,\n /// Smoothness of translation, from `0.0` to `1.0`.\n pub translational_smoothness: f64,\n /// Smoothness of rotation, from `0.0` to `1.0`.\n pub rotational_smoothness: f32,\n pub translation_speed: f64,\n pub rotation_speed: f32,\n pub acceleration_speed: f64,\n pub translation_velocity: DVec3,\n pub rotation_velocity: Vec2,\n}\n\nimpl Default for DebugCameraController {\n fn default() -> Self {\n Self {\n enabled: false,\n translational_smoothness: 0.9,\n rotational_smoothness: 0.8,\n translation_speed: 10e1,\n rotation_speed: 1e-1,\n acceleration_speed: 4.0,\n translation_velocity: Default::default(),\n rotation_velocity: Default::default(),\n }\n }\n}\n\npub fn camera_controller(\n #[cfg(feature = \"high_precision\")] frames: ReferenceFrames,\n time: Res