move(/wiki/datastructures;/wiki/introduction/storage): basic explanation doesn't belong there

Author: Longor1996

content/wiki/datastructures/index.md

@@ -7,51 +7,14 @@ categories = ["datastructures"]
 tags = ["datastructures", "storage", "spatial-acceleration"]
 +++
 
-The simplest way to store voxels is to define a three-dimensional array of elements (be it `struct`s or `integer`s), where each element represents a single voxel:
-
-```c#
-int width = ...;
-int height = ...;
-int depth = ...;
-var voxels = new VOXEL[width][height][depth];
-
-// Set a voxel:
-voxels[x][y][z] = voxel;
-
-// Get a voxel:
-var voxel = voxels[x][y][z];
-```
-
-However, because storing *arrays within arrays* often means having *pointers pointing at pointers* (which ain't good for [various reasons](/wiki/optimization) we won't get into here), it is generally recommended to use a one-dimensional array with a clearly defined *spatial indexing scheme*.
-
-Here's an example:
-
-```c#
---snip--
-// Spatial Indexing Scheme is: Y-height, Z-depth, X-width
-// The arrays size is just all axes multiplied together:
-var voxels = new VOXEL[height * depth * width];
-
-// Our Indexing Formula is the indexing scheme in reverse,
-// with the components being multiplied subsequently:
-//     x + z*width + y*width*depth
-
-// So let's define a function (here a lambda) for it:
-var idx = (int x, int y, int z) => (x + z*width + y*width*depth);
-// ^ NOTE: You may want to throw an error right here
-//         if either the coordinate components
-//         or the resulting index are out of bounds.
-
-// Set a voxel:
-voxels[idx(x,y,z)] = voxel;
-
-// Get a voxel:
-var voxel = voxels[idx(x,y,z)];
-```
-
-Now, storing voxels in a plain array like this is perfectly fine for small scenes...
-
-However, for larger scenes, we'll have to use a data-structure that allows both loading and purging *parts of our volume* (called [Chunks](/wiki/chunking) or Bricks) from memory, nearly in realtime, without slowing down the *access times* of our voxel data too much.
+Storing voxels in a plain array is perfectly fine for small scenes,
+but as we increase the size (and thus volume) of our scene,
+we will inevitably run into various limits, like the *size of our RAM*...
+
+As such, we'll have to use a data-structure that allows both
+loading and purging *parts of our volume* (called [Chunks](/wiki/chunking) or Bricks)
+from memory, nearly in realtime, without slowing down the *access times* of our voxel data,
+or the performance of world generation, *too* much.
 
 > **Note:** These techniques can often be combined.
 

content/wiki/introduction/storage.md

@@ -50,6 +50,18 @@ pub struct VoxelGrid {
   values: [[[Voxel; GRID_SIZE]; GRID_SIZE]; GRID_SIZE];
   // Well ain't that nice to look at, eh?
 }
+
+// Define methods to GET and SET voxels:
+impl VoxelGrid {
+  pub fn get(&self, x: u32, y: u32, z: u32) -> Voxel {
+    self.values[x][y][z]
+  }
+  
+  pub fn set(&self, x: u32, y: u32, z: u32, v: Voxel) {
+    *self.values[x][y][z] = v;
+  }
+}
+
 ```
 
 Now accessing it is pretty simple:
@@ -64,35 +76,26 @@ let mut volume = VoxelGrid {
 let (x,y,z) = (0, 1, 2);
 
 // Get a voxel:
-let v = volume.values[x][y][z];
+let v = volume.get(x, y, z);
 
 // Set a voxel:
-*volume.values[x][y][z] = v;
-```
-
-But what happens if `x`, `y` or `z` go *outside* the volume? We might get an error and crash!
-
-Let's prevent that by defining *accessor functions* and then ***only*** use these:
-
-```rust
-impl VoxelGrid {
-  pub fn get(&self, x: u32, y: u32, z: u32) -> Option<Voxel> {
-    self.values.get(x)?.get(y)?.get(z)
-  }
-  
-  pub fn set(&self, x: u32, y: u32, z: u32, v: Voxel) -> Option<()> {
-    *self.values.get_mut(x)?.get_mut(y)?.get_mut(z) = v;
-  }
-}
+volume.set(x, y, z, v);
 ```
 
-Alas, this shows us one of three annoyances with using 3D arrays:
-
-- Accessing elements always requires us to 'jump' trough two levels of indirection.
-- Iterating/looping over our voxels requires *three* nested loops, which is a pain to write.
-- Creating and filling a 3D array is, unsurprisingly, quite messy.
+{% info_notice() %}
+**Note on 3D arrays:**  
+In the vast majority of languages, 3D arrays are implemented as *"arrays of pointers to arrays of pointers to arrays of values"* (sometimes referred to as "jagged arrays"), which has a few downsides:
+
+- If the memory allocator doesn't play nice,
+  our innermost arrays may be spread all over the place (i.e.: fragmentation).
+- Accessing any value requires dereferencing three-ish pointers,
+  which can and will trash the cache and thus access speed.
+- Iterating/looping over them *always* requires three nested loops.
+- Creating and (de)serializing 3d arrays tends to be a messy affair.
+{% end %}
 
-As such, we will now go ahead and make our array *flat*, turning it one-dimensional!
+For a variety of reasons (see note above) and reasons yet to be revealed,
+we will now go ahead and *flatten* our array, turning it one-dimensional!
 
 ```rust
 pub struct VoxelGrid {