unified documentation of repeated float count expectations for all vector block types that use.

Included performance reasoning behind OVF design in the OVF definition file as documentation.

Author: SebastianDirks

open_vector_format.proto

@@ -488,49 +488,67 @@ message VectorBlock {
     WIRESTRUCTURE = 2;
     POINTS = 3;
   }
+  
+  //--- Vetor Block Type Definitions ---
+  //--- OVF performance: why use unstructured repeated float in vector block type definitions? ---
+
+  //The choice of using unstructured repeated float in OVF is very deliberate and the reasoning is performance.
+  //Approx. 99% of the data volume in OVF is the coordinate data. 
+  //Using repeated float enables reinterpreting the float data as an array of structs using equivalents of "memcast" in the target programming languages.
+  //This enables using different definitions of point structs without allocating again or copying the data.
+  
+  //Example use cases are struct definitions for different domain models or libraries,
+  //or Single Input Multipe Data (SIMD) vector types.
+  //Zero copy in place is the minimal overhead possible of any solution.
+  //This works in all cases where libraries use single precision floats.
+  
+  //Using repeated float also minimizes overhead in the wire format.
+  //The resulting packed proto encoding only needs a single TAG byte and a varint for the length, 
+  //resulting in only 2-5 bytes of encoding overhead per vector block.
+  //"Parsing" repeated float is a minimal overhead memcopy of the floating point data, e.g. from the file/network stream buffer.
 
   //LineSequence:
   //A lineSequence is defined by a set of vertex points (x,y), 
   //connected contiguously in the listed order by straight line segments.
   //A closed lineSequence can also be called a polygon.
   message LineSequence {
-    repeated float points = 1;
+    repeated float points = 1; // len % 2 == 0, len >= 4
   }
 
   //LineSequence3D:
   //A lineSequence3D is defined by a set of vertex points (x,y,z) in 3D space, 
   //connected contiguously in the listed order by straight line segments.
   //A closed lineSequence can also be called a polygon.
   message LineSequence3D {
-    repeated float points = 1;
+    repeated float points = 1; // len % 3 == 0, len >= 6
   }
 
   //Hatches:
   //A hatch is a set of independent straight lines,
   //each defined by one start and one end point (x,y) for 2D.
   message Hatches {
-    repeated float points = 1;
+    repeated float points = 1; // len % 4 == 0, len >= 4
   }
 
   //Hatches3D:
   //A hatch is a set of independent straight lines,
   //each defined by one start and one end point (x,y,z) for 3D.
   message Hatches3D {
-    repeated float points = 1;
+    repeated float points = 1; // len % 6 == 0, len >= 6
   }
 
   //PointSequence:
   //A point sequence is a set of points, each marked
   //for a fixed period of time. Each point consists of (x,y) for 2D.
   message PointSequence {
-    repeated float points = 1;
+    repeated float points = 1; // len % 2 == 0, len >= 2
   }
 
   //PointSequence3D:
   //A point sequence is a set of points, each marked
   //for a fixed period of time. Each point consists of (x,y,z) for 3D.
   message PointSequence3D {
-    repeated float points = 1;
+    repeated float points = 1; // len % 3 == 0, len >= 3
   }
 
   //An arc is defined by a start point on the circle,
@@ -542,7 +560,7 @@ message VectorBlock {
     double angle = 1;
     float start_dx = 2;
     float start_dy = 3;
-    repeated float centers = 4;
+    repeated float centers = 4; // len % 2 == 0, len >= 2
   }
 
   //An arc3D (edge of a plate) is defined by a start point on the circle,
@@ -555,7 +573,7 @@ message VectorBlock {
     float start_dx = 2;
     float start_dy = 3;
     float start_dz = 4;
-    repeated float centers = 5;
+    repeated float centers = 5; // len % 3 == 0, len >= 3
   }
 
   //An ellipse is defined like an arc, with additional parameters
@@ -580,7 +598,7 @@ message VectorBlock {
   //scaling linear along the vector. The goal gets priority and overwrites settings of the
   //parameter set.
   message LineSequenceParaAdapt {
-    repeated float points_with_paras = 1;
+    repeated float points_with_paras = 1; // len % 3 == 0, len >= 3
 
     AdaptedParameter parameter = 2;
     enum AdaptedParameter {
@@ -601,14 +619,14 @@ message VectorBlock {
   // Each segment: (x0, y0, cx, cy, x1, y1)  => 6 floats/segment.
   // Pack N: [x0,y0,cx,cy,x1,y1,  x0,y0,cx,cy,x1,y1,  ...]
   message QuadraticBezierHatches {
-    repeated float segments = 1;
+    repeated float segments = 1; // len % 6 == 0, len >= 6
   }
 
   // Cubic Bézier segments in 2D.
   // Each segment: (x0, y0, c1x, c1y, c2x, c2y, x1, y1)  => 8 floats/segment.
   // Pack N: [x0,y0,c1x,c1y,c2x,c2y,x1,y1,  ...]
   message CubicBezierHatches {
-    repeated float segments = 1;
+    repeated float segments = 1; // len % 8 == 0, len >= 8
   }
 
   // Linked Quadratic Bézier spline in 2D (continuous).
@@ -632,14 +650,14 @@ message VectorBlock {
   // Each segment: (x0, y0, z0, cx, cy, cz, x1, y1, z1)  => 9 floats/segment.
   // Pack N: [x0,y0,z0,cx,cy,cz,x1,y1,z1,  x0,y0,z0,cx,cy,cz,x1,y1,z1,  ...]
   message QuadraticBezierHatches3D {
-    repeated float segments = 1;
+    repeated float segments = 1; // len % 9 == 0, len >= 9
   }
 
   // Cubic Bézier segments in 3D.
   // Each segment: (x0, y0, z0, c1x, c1y, c1z, c2x, c2y, c2z, x1, y1, z1)  => 12 floats/segment.
   // Pack N: [x0,y0,z0,c1x,c1y,c1z,c2x,c2y,c2z,x1,y1,z1,  ...]
   message CubicBezierHatches3D {
-    repeated float segments = 1;
+    repeated float segments = 1; // len % 12 == 0, len >= 12
   }
 
   // Linked Quadratic Bézier spline in 3D (continuous).