feat: adding helper classes for packing uint values (#878)

* var in packets

* tests for var int packer

* tests for block packer

* adding bit count method for ulong

* adding extra comment to bit count

* fixing code smells

Assets/Mirage/Runtime/Serialization/Packers/BitHelper.cs

@@ -30,6 +30,9 @@ public static class BitHelper
     {
         /// <summary>
         /// Gets the number of bits need for <paramref name="precision"/> in range negative to positive <paramref name="max"/>
+        /// <para>
+        /// WARNING: these methods are not fast, dont use in hotpath
+        /// </para>
         /// </summary>
         /// <param name="max"></param>
         /// <param name="precision">lowest precision required, bit count will round up so real precision might be higher</param>
@@ -38,5 +41,19 @@ public static int BitCount(float max, float precision)
         {
             return Mathf.CeilToInt(Mathf.Log(2 * max / precision, 2));
         }
+
+        /// <summary>
+        /// Gets the number of bits need for <paramref name="max"/>
+        /// <para>
+        /// WARNING: these methods are not fast, dont use in hotpath
+        /// </para>
+        /// </summary>
+        /// <param name="max"></param>
+        /// <param name="precision">lowest precision required, bit count will round up so real precision might be higher</param>
+        /// <returns></returns>
+        public static int BitCount(ulong max)
+        {
+            return Mathf.CeilToInt(Mathf.Log(max, 2));
+        }
     }
 }

Assets/Mirage/Runtime/Serialization/Packers/VariableBlockPacker.cs

@@ -0,0 +1,66 @@
+/*
+MIT License
+
+Copyright (c) 2021 James Frowen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+using System;
+using System.Runtime.CompilerServices;
+
+namespace Mirage.Serialization
+{
+    public static class VariableBlockPacker
+    {
+        // todo needs doc comments
+        // todo neeeds tests
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void Pack(NetworkWriter writer, ulong value, int blockSize)
+        {
+            // always writes atleast 1 block
+            int count = 1;
+            ulong checkValue = value >> blockSize;
+            while (checkValue != 0)
+            {
+                count++;
+                checkValue >>= blockSize;
+            }
+            // count = 1, write = b0, (1<<(1-1) -1 => 1<<0 -1) => 1 -1 => 0)
+            // count = 2, write = b01
+            // count = 3, write = b011, (1<<(3-1) -1 => 1<<2 -1) => 100 - 1 => 011)
+            writer.Write((1ul << (count - 1)) - 1, count);
+            writer.Write(value, Math.Min(64, blockSize * count));
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static ulong Unpack(NetworkReader reader, int blockSize)
+        {
+            int blocks = 1;
+            // read bits till we see a zero
+            while (reader.ReadBoolean())
+            {
+                blocks++;
+            }
+
+            return reader.Read(Math.Min(64, blocks * blockSize));
+        }
+    }
+}

Assets/Mirage/Runtime/Serialization/Packers/VariableIntPacker.cs

@@ -0,0 +1,160 @@
+/*
+MIT License
+
+Copyright (c) 2021 James Frowen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+using System;
+using System.Runtime.CompilerServices;
+
+namespace Mirage.Serialization
+{
+    public sealed class VariableIntPacker
+    {
+        // todo needs doc comments
+        // todo need attribute to validate large bits based on pack type (eg if packing ushort, make sure largebits is 16 or less)
+
+        readonly int smallBitCount;
+        readonly int mediumBitsCount;
+        readonly int largeBitsCount;
+
+        readonly ulong smallValue;
+        readonly ulong mediumValue;
+        readonly ulong largeValue;
+
+        readonly bool throwIfOverLarge;
+
+        public VariableIntPacker(ulong smallValue, ulong mediumValue)
+            : this(smallValue, mediumValue, ulong.MaxValue, false) { }
+        public VariableIntPacker(ulong smallValue, ulong mediumValue, ulong largeValue, bool throwIfOverLarge = true)
+            : this(BitHelper.BitCount(smallValue), BitHelper.BitCount(mediumValue), BitHelper.BitCount(largeValue), throwIfOverLarge) { }
+
+        public static VariableIntPacker FromBitCount(int smallBits, int mediumBits)
+            => FromBitCount(smallBits, mediumBits, 64, false);
+        public static VariableIntPacker FromBitCount(int smallBits, int mediumBits, int largeBits, bool throwIfOverLarge = true)
+            => new VariableIntPacker(smallBits, mediumBits, largeBits, throwIfOverLarge);
+
+        private VariableIntPacker(int smallBits, int mediumBits, int largeBits, bool throwIfOverLarge)
+        {
+            this.throwIfOverLarge = throwIfOverLarge;
+            if (smallBits == 0) throw new ArgumentException("Small value can not be zero", nameof(smallBits));
+            if (smallBits >= mediumBits) throw new ArgumentException("Medium value must be greater than small value", nameof(mediumBits));
+            if (mediumBits >= largeBits) throw new ArgumentException("Large value must be greater than medium value", nameof(largeBits));
+            if (largeBits > 64) throw new ArgumentException("Large bits must be 64 or less", nameof(largeBits));
+            // force medium to also be 62 or less so we can use 1 write call (2 bits to say its medium + 62 value bits
+            if (mediumBits > 62) throw new ArgumentException("Medium bits must be 62 or less", nameof(mediumBits));
+
+            smallBitCount = smallBits;
+            mediumBitsCount = mediumBits;
+            largeBitsCount = largeBits;
+
+            // mask is also max value for n bits
+            smallValue = BitMask.Mask(smallBits);
+            mediumValue = BitMask.Mask(mediumBits);
+            largeValue = BitMask.Mask(largeBits);
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void PackUlong(NetworkWriter writer, ulong value)
+        {
+            pack(writer, value, 64);
+        }
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void PackUint(NetworkWriter writer, uint value)
+        {
+            pack(writer, value, 32);
+        }
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void PackUshort(NetworkWriter writer, ushort value)
+        {
+            pack(writer, value, 16);
+        }
+        void pack(NetworkWriter writer, ulong value, int maxBits)
+        {
+            if (value <= smallValue)
+            {
+                // start with b0 to say small, then value
+                writer.Write(value << 1, smallBitCount + 1);
+            }
+            else if (value <= mediumValue)
+            {
+                // start with b01 to say medium, then value
+                writer.Write(value << 2 | 0b01, mediumBitsCount + 2);
+            }
+            else if (value <= largeValue)
+            {
+                // start with b11 to say large, then value
+                // use 2 write calls here because bitCount could be 64
+                writer.Write(0b11, 2);
+                writer.Write(value, Math.Min(maxBits, largeBitsCount));
+            }
+            else
+            {
+                if (throwIfOverLarge)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), value, $"Value is over max of {largeValue}");
+                }
+                else
+                {
+                    // if no throw write MaxValue
+                    // we dont want to write value here because it will be masked and lose some high bits
+                    // need 2 write calls here because max is 64+2 bits
+                    writer.Write(0b11, 2);
+                    writer.Write(ulong.MaxValue, Math.Min(maxBits, largeBitsCount));
+                }
+            }
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ulong UnpackUlong(NetworkReader reader)
+        {
+            return unpack(reader, 64);
+        }
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public uint UnpackUint(NetworkReader reader)
+        {
+            return (uint)unpack(reader, 32);
+        }
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ushort UnpackUshort(NetworkReader reader)
+        {
+            return (ushort)unpack(reader, 16);
+        }
+        ulong unpack(NetworkReader reader, int maxBits)
+        {
+            if (!reader.ReadBoolean())
+            {
+                return reader.Read(smallBitCount);
+            }
+            else
+            {
+                if (!reader.ReadBoolean())
+                {
+                    return reader.Read(mediumBitsCount);
+                }
+                else
+                {
+                    return reader.Read(Math.Min(largeBitsCount, maxBits));
+                }
+            }
+        }
+    }
+}

Assets/Tests/Runtime/Serialization/Packers/UintBlockPackerTests.cs

@@ -0,0 +1,94 @@
+using System;
+using Mirage.Serialization;
+using NUnit.Framework;
+using Random = System.Random;
+
+namespace Mirage.Tests.Runtime.Serialization.Packers
+{
+    [TestFixture(4)]
+    [TestFixture(7)]
+    [TestFixture(8)]
+    [TestFixture(12)]
+    [TestFixture(16)]
+    public class UintBlockPackerTests : PackerTestBase
+    {
+        readonly Random random = new Random();
+        readonly int blockSize;
+
+        public UintBlockPackerTests(int blockSize)
+        {
+            this.blockSize = blockSize;
+        }
+
+
+        ulong GetRandonUlongBias()
+        {
+            return (ulong)(Math.Abs(random.NextDouble() - random.NextDouble()) * ulong.MaxValue);
+        }
+
+        uint GetRandonUintBias()
+        {
+            return (uint)(Math.Abs(random.NextDouble() - random.NextDouble()) * uint.MaxValue);
+        }
+
+        ushort GetRandonUshortBias()
+        {
+            return (ushort)(Math.Abs(random.NextDouble() - random.NextDouble()) * ushort.MaxValue);
+        }
+
+        [Test]
+        [Repeat(1000)]
+        public void UnpacksCorrectUlongValue()
+        {
+            ulong start = GetRandonUlongBias();
+            VariableBlockPacker.Pack(writer, start, blockSize);
+            ulong unpacked = VariableBlockPacker.Unpack(GetReader(), blockSize);
+
+            Assert.That(unpacked, Is.EqualTo(start));
+        }
+
+        [Test]
+        [Repeat(1000)]
+        public void UnpacksCorrectUintValue()
+        {
+            uint start = GetRandonUintBias();
+            VariableBlockPacker.Pack(writer, start, blockSize);
+            ulong unpacked = VariableBlockPacker.Unpack(GetReader(), blockSize);
+
+            Assert.That(unpacked, Is.EqualTo(start));
+        }
+
+        [Test]
+        [Repeat(1000)]
+        public void UnpacksCorrectUshortValue()
+        {
+            ushort start = GetRandonUshortBias();
+            VariableBlockPacker.Pack(writer, start, blockSize);
+            ulong unpacked = VariableBlockPacker.Unpack(GetReader(), blockSize);
+
+            Assert.That(unpacked, Is.EqualTo(start));
+        }
+
+        [Test]
+        public void WritesNplus1BitsPerBlock()
+        {
+            uint zero = 0u;
+            VariableBlockPacker.Pack(writer, zero, blockSize);
+            Assert.That(writer.BitPosition, Is.EqualTo(blockSize + 1));
+
+            ulong unpacked = VariableBlockPacker.Unpack(GetReader(), blockSize);
+            Assert.That(unpacked, Is.EqualTo(zero));
+        }
+
+        [Test]
+        public void WritesNplus1BitsPerBlock_bigger()
+        {
+            uint aboveBlockSize = (1u << blockSize) + 1u;
+            VariableBlockPacker.Pack(writer, aboveBlockSize, blockSize);
+            Assert.That(writer.BitPosition, Is.EqualTo(2 * (blockSize + 1)));
+
+            ulong unpacked = VariableBlockPacker.Unpack(GetReader(), blockSize);
+            Assert.That(unpacked, Is.EqualTo(aboveBlockSize));
+        }
+    }
+}