add region file format specification

2024-09-03 23:45:31 +03:00
parent c15abfa715
commit ea3d8b2c08
2 changed files with 41 additions and 6 deletions
@@ -0,0 +1,51 @@
+# Binary JSON Format Specification
+
+Format version: 1.0
+
+This binary data format is developed for use as binary version of JSON in [VoxelEngine-Cpp](https://github.com/MihailRis/VoxelEngine-Cpp) and not compatible with [BSON](https://bsonspec.org/spec.html) due to elements/entries syntax and type codes differences
+
+## Basic types
+
+byteorder: little-endian
+| Name    | Size    | Definition              |
+| ------- | ------- | ----------------------- |
+| byte    | 1 byte  | 8 bit unsigned integer  |
+| int16   | 2 bytes | 16 bit signed integer   |
+| int32   | 4 bytes | 32 bit signed integer   |
+| int64   | 8 bytes | 64 bit unsigned integer |
+| uint32  | 4 bytes | 32 bit unsigned integer |
+| float64 | 8 bytes | 64 bit floating point   |
+
+## Syntax (RFC 5234)
+
+```bnf
+file      = %x01 document / cdocument   file content
+document  = uint32 (*entry) %x00        uint32 stores bytes number 
+                                        of the encoded document 
+                                        including the uint32 size
+entry     = cstring value
+value     = %x01 document
+          / %x02 (*value) %x00          list of values
+          / %x03 byte                   8 bit integer
+          / %x04 int16                  16 bit integer
+          / %x05 int32                  32 bit integer
+          / %x06 int64                  64 bit integer
+          / %x07 float64                number
+          / %x08 string                 utf-8 encoded string
+          / %x09 uint32 (*byte)         bytes array
+          / %x0A                        boolean 'false'
+          / %x0B                        boolean 'true'
+          / %x0C                        null value
+cdocument = %x1F %x8B (16*byte)         gzip-compressed data:
+                                            %x01 document
+cstring   = (*%x01-FF) %x00
+string    = uint32 (*byte)              uint32 stores number of the 
+                                        encoded string bytes
+
+float64   = 8byte
+int64     = 8byte
+uint32    = 4byte
+int32     = 4byte
+int16     = 2byte
+byte      = %x00-FF
+```
@@ -0,0 +1,41 @@
+# Region File (version 2)
+
+File format BNF (RFC 5234):
+
+```bnf
+file    = header (*chunk) offsets   complete file
+header  = magic %x02 %x00           magic number, version and reserved
+                                    zero byte
+
+magic   = %x2E %x56 %x4F %x58       '.VOXREG\0'
+          %x52 %x45 %x47 %x00
+
+chunk   = int32 (*byte)             byte array with size prefix
+offsets = (1024*int32)              offsets table
+int32   = 4byte                     signed big-endian 32 bit integer
+byte    = %x00-FF                   8 bit unsigned integer
+```
+
+C struct visualization:
+
+```c
+typedef unsigned char byte;
+
+struct file {
+	// 10 bytes
+	struct {
+		char magic[8] = ".VOXREG";
+		byte version = 2;
+		byte reserved = 0;
+	} header;
+	
+	struct {
+		int32_t size; // byteorder: big-endian
+		byte* data;
+	} chunks[1024]; // file does not contain zero sizes for missing chunks
+	
+	int32_t offsets[1024]; // byteorder: big-endian
+};
+```
+
+Offsets table contains chunks positions in file. 0 means that chunk is not present in the file. Minimal valid offset is 10 (header size).