feat: each chunk must specify its data ordering

BREAKING CHANGE: the IVoxelMap.ILocalMapData format changed

src/lib/terrain/voxelmap/board/board-renderable-factory.ts

@@ -109,6 +109,7 @@ class BoardRenderableFactory extends VoxelsRenderableFactoryCpuWorker {
             size: chunkSize,
             isEmpty: chunkIsEmpty,
             data: chunkData,
+            dataOrdering: 'zyx',
         };
     }
 

src/lib/terrain/voxelmap/i-voxelmap.ts

@@ -31,11 +31,9 @@ interface ILocalMapData {
      * - bit 1: 1 if the voxel should be displayed as checkerboard, 0 otherwise
      * - bits 2-13: ID of the material
      * Use the helper "voxelmapDataPacking" to do this encoding and be future-proof.
-     *
-     * The elements should be ordered by coordinates as follow by Z first, then Y then X.
-     * For example, for a portion of the map between (0,0,0) and (2,2,2): (0,0,0) then (1,0,0) then (0,1,0) then (1,1,0) then (0,1,1) then (1,1,1)
      */
     readonly data: Uint16Array;
+    readonly dataOrdering: VoxelsChunkOrdering;
 
     /** Should be:
      * - true if there are no voxels in the data

src/lib/terrain/voxelmap/patch/patch-factory/patch-factory-base.ts

@@ -1,7 +1,7 @@
 import * as THREE from '../../../../libs/three-usage';
 import { processAsap } from '../../../../helpers/async/async-sync';
 import { vec3ToString } from '../../../../helpers/string';
-import { type IVoxelMap } from '../../i-voxelmap';
+import { type VoxelsChunkOrdering, type IVoxelMap } from '../../i-voxelmap';
 import { type VoxelsRenderable } from '../../voxelsRenderable/voxels-renderable';
 import {
     type VoxelsChunkData,
@@ -19,6 +19,7 @@ type VertexData = {
 type LocalMapData = {
     readonly size: THREE.Vector3;
     readonly data: Uint16Array;
+    readonly dataOrdering: VoxelsChunkOrdering;
     readonly isEmpty: boolean;
 };
 

src/lib/terrain/voxelmap/voxelsRenderable/voxelsRenderableFactory/merged/cpu/voxels-renderable-factory-cpu.ts

@@ -326,6 +326,13 @@ class VoxelsRenderableFactoryCpu extends VoxelsRenderableFactory {
         if (voxelsChunkData.isEmpty) {
             return [];
         }
+
+        if (voxelsChunkData.dataOrdering !== this.serializableFactory.voxelsChunkOrdering) {
+            throw new Error(
+                `Invalid data ordering: expected "${this.serializableFactory.voxelsChunkOrdering}" but received "${voxelsChunkData.dataOrdering}".`
+            );
+        }
+
         const buffer = await this.buildBuffer(voxelsChunkData);
         return this.assembleGeometryAndMaterials(buffer);
     }

src/lib/terrain/voxelmap/voxelsRenderable/voxelsRenderableFactory/merged/gpu/voxels-computer-gpu.ts

@@ -45,6 +45,8 @@ class VoxelsComputerGpu {
     private readonly localCacheBuffer: GPUBuffer;
     private readonly buffer: FaceBuffer;
 
+    private voxelsChunkOrdering: VoxelsChunkOrdering;
+
     private readonly workgroupSize = 256;
 
     private readonly promiseThrottler = new PromisesQueue(1);
@@ -59,6 +61,8 @@ class VoxelsComputerGpu {
     ) {
         this.device = device;
 
+        this.voxelsChunkOrdering = voxelsChunkOrdering;
+
         const checkerboardPattern = {
             x: +checkerboardType.includes('x'),
             y: +checkerboardType.includes('y'),
@@ -237,6 +241,12 @@ class VoxelsComputerGpu {
     }
 
     public async computeBuffer(voxelsChunkData: VoxelsChunkData): Promise<ComputationOutputs> {
+        if (voxelsChunkData.dataOrdering !== this.voxelsChunkOrdering) {
+            throw new Error(
+                `Invalid data ordering: expected "${this.voxelsChunkOrdering}" but received "${voxelsChunkData.dataOrdering}".`
+            );
+        }
+
         return this.promiseThrottler.run(async () => {
             this.device.queue.writeBuffer(
                 this.localCacheBuffer,

src/lib/terrain/voxelmap/voxelsRenderable/voxelsRenderableFactory/voxels-renderable-factory-base.ts

@@ -1,8 +1,8 @@
-import * as THREE from '../../../../libs/three-usage';
 import { nextPowerOfTwo } from '../../../../helpers/math';
 import { vec3ToString } from '../../../../helpers/string';
 import { type PackedUintFragment } from '../../../../helpers/uint-packing';
-import { type IVoxelMaterial } from '../../i-voxelmap';
+import * as THREE from '../../../../libs/three-usage';
+import { type IVoxelMaterial, type VoxelsChunkOrdering } from '../../i-voxelmap';
 import { type VoxelsMaterialUniforms, type VoxelsMaterials } from '../voxels-material';
 import { VoxelsRenderable } from '../voxels-renderable';
 
@@ -24,6 +24,7 @@ type VertexData = {
 type VoxelsChunkData = {
     readonly size: THREE.Vector3;
     readonly data: Uint16Array;
+    readonly dataOrdering: VoxelsChunkOrdering;
     readonly isEmpty: boolean;
 };
 
@@ -185,9 +186,9 @@ abstract class VoxelsRenderableFactoryBase {
 
 export {
     VoxelsRenderableFactoryBase,
+    type CheckerboardType,
     type GeometryAndMaterial,
     type Parameters,
     type VertexData,
     type VoxelsChunkData,
-    type CheckerboardType,
 };

src/test/map/trees/tree.ts

@@ -26,6 +26,7 @@ class Tree {
             size,
             isEmpty: false,
             data: new Uint16Array(size.x * size.y * size.z),
+            dataOrdering: 'zyx',
         };
         this.indexFactor = { x: 1, y: size.x, z: size.x * size.y };
         this.offset = new THREE.Vector3(-this.radiusXZ, 0, -this.radiusXZ);

src/test/map/voxel-map.ts

@@ -224,8 +224,9 @@ class VoxelMap implements IVoxelMap, IHeightmap {
             }
         }
 
-        const result = {
+        const result: ILocalMapData = {
             data,
+            dataOrdering: 'zyx',
             isEmpty,
         };