1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
//! # LodTree
//! LodTree, a simple tree data structure for doing chunk-based level of detail
//!
//! ### Goals
//! The aim of this crate is to provide a generic, easy to use tree data structure that can be used to make Lod Quadtrees, Octrees and more.
//!
//! Internally, the tree tries to keep as much memory allocated, to avoid the cost of heap allocation, and stores the actual chunks data seperate from the tree data.
//!
//! This does come at a cost, mainly, only the chunks that are going to be added and their locations can be retreived as a slice, although for most (procedural) terrain implementations
//! making new chunks and editing them will be the highest cost to do, so that shouldn't be the biggest issue.
//!
//! ### Usage:
//! Import the crate
//! ```rust
//! use lodtree::*;
//! use lodtree::coords::OctVec; // or QuadVec if you're making an octree
//! ```
//!
//! The tree is it's own struct, and accepts a chunk (anything that implements Sized) and the lod vector (Anything that implements the LodVec trait).
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::OctVec;
//! # struct Chunk {}
//! let mut tree = Tree::<Chunk, OctVec>::new();
//! ```
//!
//! If you want to update chunks due to the camera being moved, you can check if it's needed with prepare_update.
//! It takes in 3 parameters.
//!
//! Targets: where to generate the most detail around.
//!
//! The given LodVec implementations (OctVec and QuadVec) take in 4 and 3 arguments respectively.
//! The first 3/2 are the position in the tree, which is dependant on the lod level.
//! and the last parameter is the lod level. No lods smaller than this will be generated for this target.
//!
//! Detail: The amount of detail for the targets.
//! The default implementation defines this as the amount of chunks at the target lod level surrounding the target chunk.
//!
//! Chunk creator:
//! Internally a buffer for new chunks is filled, and this function is called to create the new chunk.
//! It takes in the LodVec of the position of the chunk.
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::OctVec;
//! # struct Chunk {}
//! # let mut tree = Tree::<Chunk, OctVec>::new();
//! let needs_updating = tree.prepare_update(
//! &[OctVec::new(8, 8, 8, 8)], // the target positions to generate the lod around
//! 4, // amount of detail
//! |pos| Chunk {} // and the function to construct the chunk with
//! );
//! ```
//!
//! Now, the tree is ready for an update, so now we'll want to do something with that.
//! First, we want to process all chunks that are going to be added.
//! This is the only thing the API exposes as a slice, so we can nicely iterate over that in parallel with rayon.
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::QuadVec;
//! # struct Chunk {}
//! # impl Chunk {
//! # fn expensive_init(&mut self, pos: QuadVec) {}
//! # }
//! # let mut tree = Tree::<Chunk, QuadVec>::new();
//! tree.get_chunks_to_add_slice_mut()
//! .iter_mut() // or par_iter_mut() if you're using rayon
//! .for_each(|(position, chunk)| {
//!
//! // and run expensive init, probably does something with procedural generation
//! chunk.expensive_init(*position);
//! });
//! ```
//!
//! Next, we'll also want to change the visibility of some chunks so they don't overlap with higher detail lods.
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::QuadVec;
//! # struct Chunk {}
//! # impl Chunk {
//! # fn set_visible(&mut self, v: bool) {}
//! # }
//! # let mut tree = Tree::<Chunk, QuadVec>::new();
//! // and make all chunks visible or not
//! for i in 0..tree.get_num_chunks_to_activate() {
//! tree.get_chunk_to_activate_mut(i).set_visible(true);
//! }
//!
//! for i in 0..tree.get_num_chunks_to_deactivate() {
//! tree.get_chunk_to_deactivate_mut(i).set_visible(false);
//! }
//! ```
//! We'll probably also want to do some cleanup with chunks that are removed.
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::QuadVec;
//! # struct Chunk {}
//! # impl Chunk {
//! # fn cleanup(&mut self) {}
//! # }
//! # let mut tree = Tree::<Chunk, QuadVec>::new();
//! for i in 0..tree.get_num_chunks_to_remove() {
//! tree.get_chunk_to_remove_mut(i).cleanup();
//! }
//! ```
//! And finally, actually update the tree with the new chunks.
//! Note that it's likely needed to do the prepare_update and do_update cycle a number of times before no new chunks need to be added, as the tree only adds one lod level at a time.
//! ```rust
//! # use lodtree::*;
//! # use lodtree::coords::QuadVec;
//! # struct Chunk {}
//! # let mut tree = Tree::<Chunk, QuadVec>::new();
//! tree.do_update();
//! ```
pub use crate*;
pub use crate*;