using System; using System.Diagnostics; using System.Runtime.CompilerServices; using System.Runtime.InteropServices; using Unity.Burst; using Unity.Collections.LowLevel.Unsafe; using Unity.Jobs; using static Unity.Collections.AllocatorManager; namespace Unity.Collections { /// /// An arbitrarily-sized array of bits. /// /// /// The number of allocated bytes is always a multiple of 8. For example, a 65-bit array could fit in 9 bytes, but its allocation is actually 16 bytes. /// [StructLayout(LayoutKind.Sequential)] [NativeContainer] [DebuggerDisplay("Length = {Length}, IsCreated = {IsCreated}")] [GenerateTestsForBurstCompatibility] public unsafe struct NativeBitArray : INativeDisposable { #if ENABLE_UNITY_COLLECTIONS_CHECKS internal AtomicSafetyHandle m_Safety; static readonly SharedStatic s_staticSafetyId = SharedStatic.GetOrCreate(); #endif [NativeDisableUnsafePtrRestriction] internal UnsafeBitArray* m_BitArray; internal AllocatorHandle m_Allocator; /// /// Initializes and returns an instance of NativeBitArray. /// /// The number of bits. /// The allocator to use. /// Whether newly allocated bytes should be zeroed out. public NativeBitArray(int numBits, AllocatorManager.AllocatorHandle allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory) { CollectionHelper.CheckAllocator(allocator); #if ENABLE_UNITY_COLLECTIONS_CHECKS m_Safety = CollectionHelper.CreateSafetyHandle(allocator); CollectionHelper.SetStaticSafetyId(ref m_Safety, ref s_staticSafetyId.Data, "Unity.Collections.NativeBitArray"); #endif m_BitArray = UnsafeBitArray.Alloc(allocator); m_Allocator = allocator; * m_BitArray = new UnsafeBitArray(numBits, allocator, options); } /// /// Whether this array has been allocated (and not yet deallocated). /// /// True if this array has been allocated (and not yet deallocated). public readonly bool IsCreated => m_BitArray != null && m_BitArray->IsCreated; /// /// Whether the container is empty. /// /// True if the container is empty or the container has not been constructed. public readonly bool IsEmpty => !IsCreated || Length == 0; /// /// Sets the length, expanding the capacity if necessary. /// /// The new length in bits. /// Whether newly allocated data should be zeroed out. public void Resize(int numBits, NativeArrayOptions options = NativeArrayOptions.UninitializedMemory) { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckWriteAndBumpSecondaryVersion(m_Safety); #endif m_BitArray->Resize(numBits, options); } /// /// Sets the capacity. /// /// The new capacity. public void SetCapacity(int capacityInBits) { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckWriteAndBumpSecondaryVersion(m_Safety); #endif m_BitArray->SetCapacity(capacityInBits); } /// /// Sets the capacity to match what it would be if it had been originally initialized with all its entries. /// public void TrimExcess() { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckWriteAndBumpSecondaryVersion(m_Safety); #endif m_BitArray->TrimExcess(); } /// /// Releases all resources (memory and safety handles). /// public void Dispose() { #if ENABLE_UNITY_COLLECTIONS_CHECKS if (!AtomicSafetyHandle.IsDefaultValue(m_Safety)) { AtomicSafetyHandle.CheckExistsAndThrow(m_Safety); } #endif if (!IsCreated) { return; } #if ENABLE_UNITY_COLLECTIONS_CHECKS CollectionHelper.DisposeSafetyHandle(ref m_Safety); #endif UnsafeBitArray.Free(m_BitArray, m_Allocator); m_BitArray = null; m_Allocator = Invalid; } /// /// Creates and schedules a job that will dispose this array. /// /// The handle of a job which the new job will depend upon. /// The handle of a new job that will dispose this array. The new job depends upon inputDeps. public JobHandle Dispose(JobHandle inputDeps) { #if ENABLE_UNITY_COLLECTIONS_CHECKS if (!AtomicSafetyHandle.IsDefaultValue(m_Safety)) { AtomicSafetyHandle.CheckExistsAndThrow(m_Safety); } #endif if (!IsCreated) { return inputDeps; } #if ENABLE_UNITY_COLLECTIONS_CHECKS var jobHandle = new NativeBitArrayDisposeJob { Data = new NativeBitArrayDispose { m_BitArrayData = m_BitArray, m_Allocator = m_Allocator, m_Safety = m_Safety } }.Schedule(inputDeps); AtomicSafetyHandle.Release(m_Safety); #else var jobHandle = new NativeBitArrayDisposeJob { Data = new NativeBitArrayDispose { m_BitArrayData = m_BitArray, m_Allocator = m_Allocator } }.Schedule(inputDeps); #endif m_BitArray = null; m_Allocator = Invalid; return jobHandle; } /// /// Returns the number of bits. /// /// The number of bits. public readonly int Length { [MethodImpl(MethodImplOptions.AggressiveInlining)] get { CheckRead(); return CollectionHelper.AssumePositive(m_BitArray->Length); } } /// /// Returns the capacity number of bits. /// /// The capacity number of bits. public readonly int Capacity { [MethodImpl(MethodImplOptions.AggressiveInlining)] get { CheckRead(); return CollectionHelper.AssumePositive(m_BitArray->Capacity); } } /// /// Sets all the bits to 0. /// public void Clear() { CheckWrite(); m_BitArray->Clear(); } /// /// Returns a native array that aliases the content of this array. /// /// The type of elements in the aliased array. /// Thrown if the number of bits in this array /// is not evenly divisible by the size of T in bits (`sizeof(T) * 8`). /// A native array that aliases the content of this array. [GenerateTestsForBurstCompatibility(GenericTypeArguments = new [] { typeof(int) })] public NativeArray AsNativeArray() where T : unmanaged { CheckReadBounds(); var bitsPerElement = UnsafeUtility.SizeOf() * 8; var length = m_BitArray->Length / bitsPerElement; var array = NativeArrayUnsafeUtility.ConvertExistingDataToNativeArray(m_BitArray->Ptr, length, Allocator.None); #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.UseSecondaryVersion(ref m_Safety); NativeArrayUnsafeUtility.SetAtomicSafetyHandle(ref array, m_Safety); #endif return array; } /// /// Sets the bit at an index to 0 or 1. /// /// Index of the bit to set. /// True for 1, false for 0. public void Set(int pos, bool value) { CheckWrite(); m_BitArray->Set(pos, value); } /// /// Sets a range of bits to 0 or 1. /// /// /// The range runs from index `pos` up to (but not including) `pos + numBits`. /// No exception is thrown if `pos + numBits` exceeds the length. /// /// Index of the first bit to set. /// True for 1, false for 0. /// Number of bits to set. /// Thrown if pos is out of bounds or if numBits is less than 1. public void SetBits(int pos, bool value, int numBits) { CheckWrite(); m_BitArray->SetBits(pos, value, numBits); } /// /// Copies bits of a ulong to bits in this array. /// /// /// The destination bits in this array run from index pos up to (but not including) `pos + numBits`. /// No exception is thrown if `pos + numBits` exceeds the length. /// /// The lowest bit of the ulong is copied to the first destination bit; the second-lowest bit of the ulong is /// copied to the second destination bit; and so forth. /// /// Index of the first bit to set. /// Unsigned long from which to copy bits. /// Number of bits to set (must be between 1 and 64). /// Thrown if pos is out of bounds or if numBits is not between 1 and 64. public void SetBits(int pos, ulong value, int numBits = 1) { CheckWrite(); m_BitArray->SetBits(pos, value, numBits); } /// /// Returns a ulong which has bits copied from this array. /// /// /// The source bits in this array run from index pos up to (but not including) `pos + numBits`. /// No exception is thrown if `pos + numBits` exceeds the length. /// /// The first source bit is copied to the lowest bit of the ulong; the second source bit is copied to the second-lowest bit of the ulong; and so forth. Any remaining bits in the ulong will be 0. /// /// Index of the first bit to get. /// Number of bits to get (must be between 1 and 64). /// Thrown if pos is out of bounds or if numBits is not between 1 and 64. /// A ulong which has bits copied from this array. public ulong GetBits(int pos, int numBits = 1) { CheckRead(); return m_BitArray->GetBits(pos, numBits); } /// /// Returns true if the bit at an index is 1. /// /// Index of the bit to test. /// True if the bit at the index is 1. /// Thrown if `pos` is out of bounds. public bool IsSet(int pos) { CheckRead(); return m_BitArray->IsSet(pos); } /// /// Copies a range of bits from this array to another range in this array. /// /// /// The bits to copy run from index `srcPos` up to (but not including) `srcPos + numBits`. /// The bits to set run from index `dstPos` up to (but not including) `dstPos + numBits`. /// /// The ranges may overlap, but the result in the overlapping region is undefined. /// /// Index of the first bit to set. /// Index of the first bit to copy. /// Number of bits to copy. /// Thrown if either `dstPos + numBits` or `srcPos + numBits` exceed the length of this array. public void Copy(int dstPos, int srcPos, int numBits) { CheckWrite(); m_BitArray->Copy(dstPos, srcPos, numBits); } /// /// Copies a range of bits from an array to a range of bits in this array. /// /// /// The bits to copy in the source array run from index srcPos up to (but not including) `srcPos + numBits`. /// The bits to set in the destination array run from index dstPos up to (but not including) `dstPos + numBits`. /// /// When the source and destination are the same array, the ranges may still overlap, but the result in the overlapping region is undefined. /// /// Index of the first bit to set. /// The source array. /// Index of the first bit to copy. /// The number of bits to copy. /// Thrown if either `dstPos + numBits` or `srcBitArray + numBits` exceed the length of this array. public void Copy(int dstPos, ref NativeBitArray srcBitArray, int srcPos, int numBits) { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckReadAndThrow(srcBitArray.m_Safety); #endif CheckWrite(); m_BitArray->Copy(dstPos, ref *srcBitArray.m_BitArray, srcPos, numBits); } /// /// Finds the first length-*N* contiguous sequence of 0 bits in this bit array. /// /// Index at which to start searching. /// Number of contiguous 0 bits to look for. /// The index in this array where the sequence is found. The index will be greater than or equal to `pos`. /// Returns -1 if no occurrence is found. public int Find(int pos, int numBits) { CheckRead(); return m_BitArray->Find(pos, numBits); } /// /// Finds the first length-*N* contiguous sequence of 0 bits in this bit array. Searches only a subsection. /// /// Index at which to start searching. /// Number of contiguous 0 bits to look for. /// Number of bits to search. /// The index in this array where the sequence is found. The index will be greater than or equal to `pos` but less than `pos + count`. /// Returns -1 if no occurrence is found. public int Find(int pos, int count, int numBits) { CheckRead(); return m_BitArray->Find(pos, count, numBits); } /// /// Returns true if none of the bits in a range are 1 (*i.e.* all bits in the range are 0). /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// Returns true if none of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public bool TestNone(int pos, int numBits = 1) { CheckRead(); return m_BitArray->TestNone(pos, numBits); } /// /// Returns true if at least one of the bits in a range is 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// True if one ore more of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public bool TestAny(int pos, int numBits = 1) { CheckRead(); return m_BitArray->TestAny(pos, numBits); } /// /// Returns true if all of the bits in a range are 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// True if all of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public bool TestAll(int pos, int numBits = 1) { CheckRead(); return m_BitArray->TestAll(pos, numBits); } /// /// Returns the number of bits in a range that are 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// The number of bits in a range of bits that are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public int CountBits(int pos, int numBits = 1) { CheckRead(); return m_BitArray->CountBits(pos, numBits); } /// /// Returns a readonly version of this NativeBitArray instance. /// /// ReadOnly containers point to the same underlying data as the NativeBitArray it is made from. /// ReadOnly instance for this. public ReadOnly AsReadOnly() { return new ReadOnly(ref this); } /// /// A read-only alias for the value of a UnsafeBitArray. Does not have its own allocated storage. /// [NativeContainer] [NativeContainerIsReadOnly] public struct ReadOnly { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle m_Safety; internal static readonly SharedStatic s_staticSafetyId = SharedStatic.GetOrCreate(); #endif [NativeDisableUnsafePtrRestriction] internal UnsafeBitArray.ReadOnly m_BitArray; /// /// Whether this array has been allocated (and not yet deallocated). /// /// True if this array has been allocated (and not yet deallocated). public readonly bool IsCreated => m_BitArray.IsCreated; /// /// Whether the container is empty. /// /// True if the container is empty or the container has not been constructed. public readonly bool IsEmpty => m_BitArray.IsEmpty; internal ReadOnly(ref NativeBitArray data) { m_BitArray = data.m_BitArray->AsReadOnly(); #if ENABLE_UNITY_COLLECTIONS_CHECKS m_Safety = data.m_Safety; CollectionHelper.SetStaticSafetyId(ref m_Safety, ref s_staticSafetyId.Data); #endif } /// /// Returns the number of bits. /// /// The number of bits. public readonly int Length { get { CheckRead(); return CollectionHelper.AssumePositive(m_BitArray.Length); } } /// /// Returns a ulong which has bits copied from this array. /// /// /// The source bits in this array run from index pos up to (but not including) `pos + numBits`. /// No exception is thrown if `pos + numBits` exceeds the length. /// /// The first source bit is copied to the lowest bit of the ulong; the second source bit is copied to the second-lowest bit of the ulong; and so forth. Any remaining bits in the ulong will be 0. /// /// Index of the first bit to get. /// Number of bits to get (must be between 1 and 64). /// Thrown if pos is out of bounds or if numBits is not between 1 and 64. /// A ulong which has bits copied from this array. public readonly ulong GetBits(int pos, int numBits = 1) { CheckRead(); return m_BitArray.GetBits(pos, numBits); } /// /// Returns true if the bit at an index is 1. /// /// Index of the bit to test. /// True if the bit at the index is 1. /// Thrown if `pos` is out of bounds. public readonly bool IsSet(int pos) { CheckRead(); return m_BitArray.IsSet(pos); } /// /// Finds the first length-*N* contiguous sequence of 0 bits in this bit array. /// /// Index at which to start searching. /// Number of contiguous 0 bits to look for. /// The index in this array where the sequence is found. The index will be greater than or equal to `pos`. /// Returns -1 if no occurrence is found. public readonly int Find(int pos, int numBits) { CheckRead(); return m_BitArray.Find(pos, numBits); } /// /// Finds the first length-*N* contiguous sequence of 0 bits in this bit array. Searches only a subsection. /// /// Index at which to start searching. /// Number of contiguous 0 bits to look for. /// Number of bits to search. /// The index in this array where the sequence is found. The index will be greater than or equal to `pos` but less than `pos + count`. /// Returns -1 if no occurrence is found. public readonly int Find(int pos, int count, int numBits) { CheckRead(); return m_BitArray.Find(pos, count, numBits); } /// /// Returns true if none of the bits in a range are 1 (*i.e.* all bits in the range are 0). /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// Returns true if none of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public readonly bool TestNone(int pos, int numBits = 1) { CheckRead(); return m_BitArray.TestNone(pos, numBits); } /// /// Returns true if at least one of the bits in a range is 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// True if one ore more of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public readonly bool TestAny(int pos, int numBits = 1) { CheckRead(); return m_BitArray.TestAny(pos, numBits); } /// /// Returns true if all of the bits in a range are 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// True if all of the bits in range `pos` up to (but not including) `pos + numBits` are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public readonly bool TestAll(int pos, int numBits = 1) { CheckRead(); return m_BitArray.TestAll(pos, numBits); } /// /// Returns the number of bits in a range that are 1. /// /// Index of the bit at which to start searching. /// Number of bits to test. Defaults to 1. /// The number of bits in a range of bits that are 1. /// Thrown if `pos` is out of bounds or `numBits` is less than 1. public readonly int CountBits(int pos, int numBits = 1) { CheckRead(); return m_BitArray.CountBits(pos, numBits); } [Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")] readonly void CheckRead() { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckReadAndThrow(m_Safety); #endif } } [Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")] readonly void CheckRead() { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckReadAndThrow(m_Safety); #endif } [Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS"), Conditional("UNITY_DOTS_DEBUG")] void CheckReadBounds() where T : unmanaged { CheckRead(); var bitsPerElement = UnsafeUtility.SizeOf() * 8; var length = m_BitArray->Length / bitsPerElement; if (length == 0) { throw new InvalidOperationException($"Number of bits in the NativeBitArray {m_BitArray->Length} is not sufficient to cast to NativeArray {UnsafeUtility.SizeOf() * 8}."); } else if (m_BitArray->Length != bitsPerElement* length) { throw new InvalidOperationException($"Number of bits in the NativeBitArray {m_BitArray->Length} couldn't hold multiple of T {UnsafeUtility.SizeOf()}. Output array would be truncated."); } } [Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")] void CheckWrite() { #if ENABLE_UNITY_COLLECTIONS_CHECKS AtomicSafetyHandle.CheckWriteAndThrow(m_Safety); #endif } } [NativeContainer] [GenerateTestsForBurstCompatibility] internal unsafe struct NativeBitArrayDispose { [NativeDisableUnsafePtrRestriction] public UnsafeBitArray* m_BitArrayData; public AllocatorHandle m_Allocator; #if ENABLE_UNITY_COLLECTIONS_CHECKS public AtomicSafetyHandle m_Safety; #endif public void Dispose() { UnsafeBitArray.Free(m_BitArrayData, m_Allocator); } } [BurstCompile] internal unsafe struct NativeBitArrayDisposeJob : IJob { public NativeBitArrayDispose Data; public void Execute() { Data.Dispose(); } } } namespace Unity.Collections.LowLevel.Unsafe { /// /// Unsafe helper methods for NativeBitArray. /// [GenerateTestsForBurstCompatibility] public static class NativeBitArrayUnsafeUtility { #if ENABLE_UNITY_COLLECTIONS_CHECKS /// /// Returns an array's atomic safety handle. /// /// Array from which to get an AtomicSafetyHandle. /// This array's atomic safety handle. [GenerateTestsForBurstCompatibility(RequiredUnityDefine = "ENABLE_UNITY_COLLECTIONS_CHECKS", CompileTarget = GenerateTestsForBurstCompatibilityAttribute.BurstCompatibleCompileTarget.Editor)] public static AtomicSafetyHandle GetAtomicSafetyHandle(in NativeBitArray container) { return container.m_Safety; } /// /// Sets an array's atomic safety handle. /// /// Array which the AtomicSafetyHandle is for. /// Atomic safety handle for this array. [GenerateTestsForBurstCompatibility(RequiredUnityDefine = "ENABLE_UNITY_COLLECTIONS_CHECKS", CompileTarget = GenerateTestsForBurstCompatibilityAttribute.BurstCompatibleCompileTarget.Editor)] public static void SetAtomicSafetyHandle(ref NativeBitArray container, AtomicSafetyHandle safety) { container.m_Safety = safety; } #endif /// /// Returns a bit array with content aliasing a buffer. /// /// A buffer. /// Size of the buffer in bytes. Must be a multiple of 8. /// The allocator that was used to create the buffer. /// A bit array with content aliasing a buffer. public static unsafe NativeBitArray ConvertExistingDataToNativeBitArray(void* ptr, int sizeInBytes, AllocatorManager.AllocatorHandle allocator) { var bitArray = UnsafeBitArray.Alloc(Allocator.Persistent); *bitArray = new UnsafeBitArray(ptr, sizeInBytes, allocator); return new NativeBitArray { m_BitArray = bitArray, m_Allocator = Allocator.Persistent, }; } } }