| | | 1 | | //======================================================================= |
| | | 2 | | // GridCoveredAddressCursor.cs |
| | | 3 | | //======================================================================= |
| | | 4 | | // MIT License, Copyright (c) 2024-present David Oravsky (mrdav30) |
| | | 5 | | // See LICENSE file in the project root for full license information. |
| | | 6 | | //======================================================================= |
| | | 7 | | |
| | | 8 | | using System; |
| | | 9 | | using FixedMathSharp; |
| | | 10 | | using GridForge.Configuration; |
| | | 11 | | using GridForge.Spatial; |
| | | 12 | | |
| | | 13 | | namespace GridForge.Grids.Topology; |
| | | 14 | | |
| | | 15 | | |
| | | 16 | | |
| | | 17 | | /// <summary>Stores caller-owned bounded progress for a value-only covered-address query.</summary> |
| | | 18 | | /// <remarks> |
| | | 19 | | /// Construct with the maximum eligible generation count, begin through <see cref="GridWorld"/>, then |
| | | 20 | | /// supply the next canonical generation-input slice to each advance call until it is consumed. Once all |
| | | 21 | | /// declared generations are bound, pass an empty input span. The cursor retains no live grid or voxel. |
| | | 22 | | /// </remarks> |
| | | 23 | | public sealed partial class GridCoveredAddressCursor |
| | | 24 | | { |
| | | 25 | | private const long LogicalStateBytes = 512L; |
| | | 26 | | private const long ArrayHeaderBytes = 24L; |
| | | 27 | | private const long BoundGenerationBytes = 160L; |
| | | 28 | | |
| | | 29 | | |
| | | 30 | | |
| | | 31 | | internal readonly BoundGeneration[] Generations; |
| | | 32 | | internal long WorldSpawnToken; |
| | | 33 | | internal uint WorldVersion; |
| | | 34 | | internal ulong WorldChangeSequence; |
| | | 35 | | internal Vector3d QueryMinimum; |
| | | 36 | | internal Vector3d QueryMaximum; |
| | | 37 | | internal GridConfigurationKey FilterConfigurationKey; |
| | | 38 | | internal GridCoveredAddressGeneration LastBoundGeneration; |
| | | 39 | | internal GridCoveredAddress PendingOutput; |
| | | 40 | | internal VoxelIndex CurrentAddress; |
| | | 41 | | internal int ExpectedGenerationCount; |
| | | 42 | | internal int BoundGenerationCount; |
| | | 43 | | internal int RangeGenerationCount; |
| | | 44 | | internal int GenerationOrdinal; |
| | | 45 | | internal bool HasConfigurationFilter; |
| | | 46 | | internal bool HasLastBoundGeneration; |
| | | 47 | | internal bool HasPendingOutput; |
| | | 48 | | internal bool HasCurrentAddress; |
| | | 49 | | internal GridCoveredAddressCursorStatus CurrentStatus; |
| | | 50 | | |
| | | 51 | | /// <summary>Initializes reusable storage for at most <paramref name="generationCapacity"/> eligible grids.</summary |
| | 24 | 52 | | public GridCoveredAddressCursor(int generationCapacity) |
| | | 53 | | { |
| | 24 | 54 | | ChronicleGuard.ThrowIfNegative(generationCapacity, nameof(generationCapacity)); |
| | 24 | 55 | | Generations = generationCapacity == 0 |
| | 24 | 56 | | ? Array.Empty<BoundGeneration>() |
| | 24 | 57 | | : new BoundGeneration[generationCapacity]; |
| | 24 | 58 | | } |
| | | 59 | | |
| | | 60 | | /// <summary>The maximum eligible generation count accepted by this cursor.</summary> |
| | 1 | 61 | | public int GenerationCapacity => Generations.Length; |
| | | 62 | | |
| | | 63 | | /// <summary>The deterministic logical bytes retained by this cursor and its owned generation storage.</summary> |
| | | 64 | | /// <remarks>Shared empty-array storage is not charged.</remarks> |
| | 4 | 65 | | public long RetainedBytes => checked( |
| | 4 | 66 | | LogicalStateBytes |
| | 4 | 67 | | + (Generations.Length == 0 |
| | 4 | 68 | | ? 0L |
| | 4 | 69 | | : ArrayHeaderBytes + ((long)Generations.Length * BoundGenerationBytes))); |
| | | 70 | | |
| | | 71 | | /// <summary>The current query state.</summary> |
| | 3 | 72 | | public GridCoveredAddressCursorStatus Status => CurrentStatus; |
| | | 73 | | |
| | | 74 | | /// <summary>The cumulative number of generation validation and spatial lookup probes.</summary> |
| | | 75 | | public ulong LookupProbeOrdinal { get; internal set; } |
| | | 76 | | |
| | | 77 | | /// <summary>The cumulative number of topology-address probes.</summary> |
| | | 78 | | public ulong AddressProbeOrdinal { get; internal set; } |
| | | 79 | | |
| | | 80 | | /// <summary>The cumulative number of covered addresses emitted.</summary> |
| | | 81 | | public ulong OutputOrdinal { get; internal set; } |
| | | 82 | | |
| | | 83 | | /// <summary>The exact committed world revision bound by this cursor.</summary> |
| | | 84 | | public GridCoveredAddressRunStamp RunStamp => |
| | 19 | 85 | | CurrentStatus == GridCoveredAddressCursorStatus.Stale |
| | 19 | 86 | | ? default |
| | 19 | 87 | | : new GridCoveredAddressRunStamp( |
| | 19 | 88 | | WorldSpawnToken, |
| | 19 | 89 | | WorldVersion, |
| | 19 | 90 | | WorldChangeSequence); |
| | | 91 | | |
| | | 92 | | internal bool Begin( |
| | | 93 | | long worldSpawnToken, |
| | | 94 | | uint worldVersion, |
| | | 95 | | ulong worldChangeSequence, |
| | | 96 | | Vector3d queryMinimum, |
| | | 97 | | Vector3d queryMaximum, |
| | | 98 | | int expectedGenerationCount, |
| | | 99 | | bool hasConfigurationFilter, |
| | | 100 | | GridConfigurationKey filterConfigurationKey) |
| | | 101 | | { |
| | 28 | 102 | | if (expectedGenerationCount < 0 || expectedGenerationCount > Generations.Length) |
| | | 103 | | { |
| | 2 | 104 | | MarkStale(); |
| | 2 | 105 | | return false; |
| | | 106 | | } |
| | | 107 | | |
| | 26 | 108 | | WorldSpawnToken = worldSpawnToken; |
| | 26 | 109 | | WorldVersion = worldVersion; |
| | 26 | 110 | | WorldChangeSequence = worldChangeSequence; |
| | 26 | 111 | | QueryMinimum = queryMinimum; |
| | 26 | 112 | | QueryMaximum = queryMaximum; |
| | 26 | 113 | | ExpectedGenerationCount = expectedGenerationCount; |
| | 26 | 114 | | BoundGenerationCount = 0; |
| | 26 | 115 | | RangeGenerationCount = 0; |
| | 26 | 116 | | GenerationOrdinal = 0; |
| | 26 | 117 | | HasConfigurationFilter = hasConfigurationFilter; |
| | 26 | 118 | | FilterConfigurationKey = filterConfigurationKey; |
| | 26 | 119 | | LastBoundGeneration = default; |
| | 26 | 120 | | PendingOutput = default; |
| | 26 | 121 | | CurrentAddress = default; |
| | 26 | 122 | | HasPendingOutput = false; |
| | 26 | 123 | | HasCurrentAddress = false; |
| | 26 | 124 | | HasLastBoundGeneration = false; |
| | 26 | 125 | | LookupProbeOrdinal = 0; |
| | 26 | 126 | | AddressProbeOrdinal = 0; |
| | 26 | 127 | | OutputOrdinal = 0; |
| | 26 | 128 | | CurrentStatus = expectedGenerationCount == 0 |
| | 26 | 129 | | ? GridCoveredAddressCursorStatus.Complete |
| | 26 | 130 | | : GridCoveredAddressCursorStatus.More; |
| | 26 | 131 | | return true; |
| | | 132 | | } |
| | | 133 | | |
| | | 134 | | internal GridCoveredAddressCursorStatus MarkStale() |
| | | 135 | | { |
| | 9 | 136 | | WorldSpawnToken = 0; |
| | 9 | 137 | | WorldVersion = 0; |
| | 9 | 138 | | WorldChangeSequence = 0; |
| | 9 | 139 | | QueryMinimum = default; |
| | 9 | 140 | | QueryMaximum = default; |
| | 9 | 141 | | FilterConfigurationKey = default; |
| | 9 | 142 | | LastBoundGeneration = default; |
| | 9 | 143 | | PendingOutput = default; |
| | 9 | 144 | | CurrentAddress = default; |
| | 9 | 145 | | ExpectedGenerationCount = 0; |
| | 9 | 146 | | BoundGenerationCount = 0; |
| | 9 | 147 | | RangeGenerationCount = 0; |
| | 9 | 148 | | GenerationOrdinal = 0; |
| | 9 | 149 | | HasConfigurationFilter = false; |
| | 9 | 150 | | HasLastBoundGeneration = false; |
| | 9 | 151 | | HasPendingOutput = false; |
| | 9 | 152 | | HasCurrentAddress = false; |
| | 9 | 153 | | LookupProbeOrdinal = 0; |
| | 9 | 154 | | AddressProbeOrdinal = 0; |
| | 9 | 155 | | OutputOrdinal = 0; |
| | 9 | 156 | | CurrentStatus = GridCoveredAddressCursorStatus.Stale; |
| | 9 | 157 | | return CurrentStatus; |
| | | 158 | | } |
| | | 159 | | } |