Game.Rendering.PreCullingSystem

Assembly: Game (runtime assembly containing game systems)
Namespace: Game.Rendering

Type: class

Base: GameSystemBase, IPostDeserialize

Summary:
PreCullingSystem collects and maintains per-entity culling metadata used by the rendering pipeline. It runs a set of Burst jobs to determine which entities pass or fail distance/LOD & layer visibility tests ("pre-culling"), populates a compact PreCullingData list for near-camera processing, and exposes that list for other systems (readers/writers). It integrates with search trees (static objects, nets, lanes), schedules and combines many jobs (initialize, query, relative/temp handling, tree culling, action processing, resize/filter updates) and manages state that tracks changes between frames (previous camera/LOD/visibility masks). The system also exposes a fade container entity used for fade batch management.

Fields

private RenderingSystem m_RenderingSystem
The rendering system this pre-culling system queries for frame LOD, frame index/time and other rendering state.
private UndergroundViewSystem m_UndergroundViewSystem
Tracks underground pipeline/subpipeline/waterway visibility and utility types used to influence culling masks.
private BatchMeshSystem m_BatchMeshSystem
Used to coordinate batch caching/completion with the culling update.
private BatchDataSystem m_BatchDataSystem
Provides level-of-detail and other batch-related parameters used by LOD calculations.
private Game.Objects.SearchSystem m_ObjectSearchSystem
Provides static object search tree (quad-tree) used by tree-based culling.
private Game.Net.SearchSystem m_NetSearchSystem
Provides net and lane search trees used by tree-based culling for roads/lanes.
private ToolSystem m_ToolSystem
Used to detect editor/tools state (e.g., whether zones are required).
private CameraUpdateSystem m_CameraUpdateSystem
Used to read camera/view parameters (viewer forward, LOD parameters, camera position).
private TerrainSystem m_TerrainSystem
Provides terrain height data when computing object bounds that depend on terrain.
private EntityQuery m_InitializeQuery
EntityQuery used for initialization pass over culling info components.
private EntityQuery m_EventQuery
EntityQuery used to process events that influence culling (e.g., renters/color updates).
private EntityQuery m_CullingInfoQuery
Main query that targets entities with CullingInfo for normal runtime updates.
private EntityQuery m_TempQuery
Query for temp/interpolated entities that need special handling.
private float3 m_PrevCameraPosition
Previous-frame camera position used to compute cross-frame LOD/visibility diffs.
private float3 m_PrevCameraDirection
Previous-frame camera forward vector used for cross-frame LOD/visibility diffs.
private float4 m_PrevLodParameters
Previous-frame LOD parameters (packed floats) used to detect LOD transitions.
private BoundsMask m_PrevVisibleMask
Mask of layers that were visible previous frame (to identify becameVisible/becameHidden).
private QueryFlags m_PrevQueryFlags
Previously used query flags (Unspawned/Zones) used to pick entity queries.
private Dictionary<QueryFlags, EntityQuery> m_CullingQueries
Cache of entity queries for different QueryFlags combinations for the main culling pass.
private Dictionary<QueryFlags, EntityQuery> m_RelativeQueries
Cache of entity queries for "relative" entity updates (entities that follow parent bounds).
private Dictionary<QueryFlags, EntityQuery> m_RemoveQueries
Cache of entity queries for remove/deleted handling.
private NativeList<PreCullingData> m_CullingData
Main native list holding PreCullingData entries for entities that currently passed culling.
private NativeList<PreCullingData> m_UpdatedData
Native list collected each frame of pre-culling entries that need to be processed/updated.
private Entity m_FadeContainer
An Entity created to hold fade batches (FadeContainer), included as a permanent entry in m_CullingData.
private JobHandle m_WriteDependencies
Handle used to track jobs that write to the culling data; callers can combine with this to ensure safe reads.
private JobHandle m_ReadDependencies
Handle used to track readers of culling data and combined for writers.
private bool m_ResetPrevious
When true, previous-frame state is reset so that everything is treated as newly visible/changed.
private bool m_Loaded
Flag set during PostDeserialize to indicate the system was (re)loaded and needs a full update.
private TypeHandle __TypeHandle
Internal struct used to store Component/Buffer/Shared handles required by jobs. (auto-generated helper)

Properties

public BoundsMask visibleMask { get; private set; }
Current computed visible mask (which layers are visible this frame). Updated during OnUpdate.
public BoundsMask becameVisible { get; private set; }
Mask of layers that became visible this frame (visibleMask & ~previousVisibleMask). Useful to force checks when layers turn on.
public BoundsMask becameHidden { get; private set; }
Mask of layers that became hidden this frame (previousVisibleMask & ~visibleMask). Used to force removals/cross-fades.

Constructors

public PreCullingSystem()
Default constructor. The system sets up native lists and creates a fade container entity during OnCreate.

Methods

[Preserve] protected override void OnCreate() : System.Void
Initializes references to other systems, creates entity queries, allocates native lists (m_CullingData, m_UpdatedData), creates m_FadeContainer, and sets initial previous-camera/LOD state.
[Preserve] protected override void OnDestroy() : System.Void
Completes outstanding write/read dependencies and disposes native lists. Cleans up resources when the system is destroyed.
public void PostDeserialize(Context context) : System.Void
Implements IPostDeserialize. Called after serialization load; ensures pending job handles complete, clears fade containers' buffers, re-initializes culling data and resets culling state. Sets m_Loaded = true to request full initialization.
public void ResetCulling() : System.Void
Flags the system to reset previous-frame state on next update (m_ResetPrevious = true). Useful if external state changes require treating all entities as newly visible.
public Entity GetFadeContainer() : Entity
Returns the fade container entity managed by the system. This entity holds fade/batch buffers for cross-fading.
public NativeList<PreCullingData> GetCullingData(bool readOnly, out JobHandle dependencies) : NativeList
Provides access to the underlying m_CullingData. Also returns job dependency that must be respected by callers. If readOnly is true the returned dependency ensures writers are complete; otherwise both read/write dependencies are combined.
public NativeList<PreCullingData> GetUpdatedData(bool readOnly, out JobHandle dependencies) : NativeList
Provides access to m_UpdatedData and dependency similar to GetCullingData.
public void AddCullingDataReader(JobHandle dependencies) : System.Void
Register an external read dependency (combines into m_ReadDependencies) so the system can avoid overwriting data while readers run.
public void AddCullingDataWriter(JobHandle dependencies) : System.Void
Register an external writer dependency; replaces m_WriteDependencies. Used to synchronize writers.
private bool GetLoaded() : bool
Internal helper used in OnUpdate to consume the m_Loaded flag once (returns true once after PostDeserialize).
[Preserve] protected override void OnUpdate() : System.Void
Main per-frame update. Steps:
Ensure previous write/read dependencies are complete.
Query camera/LOD parameters (via CameraUpdateSystem and BatchDataSystem).
Compute the visible layer mask (incl. underground toggles & markers).
Build and schedule multiple jobs:
- Tree-based culling jobs (TreeCullingJob1/2) operating on quadtrees for static objects, nets and lanes.
- InitializeCullingJob: fills/updates CullingInfo for entities and sets flags.
- EventCullingJob: processes building/route events that affect culling.
- QueryCullingJob: processes standard culling queries for entities (with/without TransformFrame buffers).
- QueryRemoveJob: handles deleted/applied removal actions.
- RelativeCullingJob: updates bounds for entities that follow a parent (owner or current vehicle).
- TempCullingJob: handles temporary entities and interpolation cases.
- VerifyVisibleJob (optional when resetting or layers hide): ensures previously visible items are validated/removed.
- CullingActionJob: consumes produced CullingAction queue and updates CullingInfo / m_CullingData / handles overflow.
- ResizeCullingDataJob + FilterUpdatesJob: finalize and filter updated data.
Registers tree/terrain readers with respective systems and updates internal previous-frame state. This method orchestrates all pre-culling work and arranges dependencies so results are safe to read.
private void InitializeCullingData() : System.Void
Clears m_CullingData and inserts a permanent entry for the fade container (m_FadeContainer) marked as PassedCulling & FadeContainer. Ensures the fade container is always present in the list.
private EntityQuery GetCullingQuery(QueryFlags flags) : EntityQuery
Returns (and caches) an EntityQuery configured for the main culling pass, adjusted by flags (include/exclude Unspawned, include zones or not). The query selects entities with CullingInfo and a set of Any and None components appropriate for the flags.
private EntityQuery GetRelativeQuery(QueryFlags flags) : EntityQuery
Returns (and caches) an EntityQuery for entities that have Relative components and need to copy parent's bounds. Flags control inclusion of Unspawned.
private EntityQuery GetRemoveQuery(QueryFlags flags) : EntityQuery
Returns (and caches) a query used to detect entities that need removal handling (Deleted, optionally Block/Unspawned depending on flags).
private QueryFlags GetQueryFlags() : QueryFlags
Computes QueryFlags bitmask for the current frame based on m_RenderingSystem.unspawnedVisible and whether current active tool requires zones.
[MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignQueries(ref SystemState state) : System.Void
Internal helper used by compiled-once path; assigns queries (auto-generated, no-op here).
protected override void OnCreateForCompiler() : System.Void
Auto-generated hookup used by the compiled environment to assign handles; calls __AssignQueries and populates __TypeHandle.
private void PostDeserialize(Context context)
(Already listed above under IPostDeserialize — retains responsibility for resetting culling after load.)

Note: The class defines many nested Burst jobs and helper structs (TreeCullingJob1/2, TreeCullingIterator, InitializeCullingJob, EventCullingJob, QueryCullingJob, QueryRemoveJob, RelativeCullingJob, TempCullingJob, VerifyVisibleJob, CullingActionJob, ResizeCullingDataJob, FilterUpdatesJob, and others). These are the worker units that perform the parallel culling evaluation and update m_CullingData.

Usage Example

// Get the PreCullingSystem from the world (managed system)
var preCulling = World.DefaultGameObjectInjectionWorld.GetExistingSystemManaged<Game.Rendering.PreCullingSystem>();

// Ensure any pending writers are complete before reading
JobHandle readDeps;
var cullingData = preCulling.GetCullingData(readOnly: true, out readDeps);
readDeps.Complete(); // ensure the system has finished writing

// Iterate current pre-culling entries (example)
for (int i = 0; i < cullingData.Length; i++)
{
    var entry = cullingData[i];
    // process entry.m_Entity / entry.m_Flags / etc.
}

// If external changes require re-evaluating culling from scratch:
preCulling.ResetCulling();

// Access the fade container entity (used for fade batches)
Entity fadeContainer = preCulling.GetFadeContainer();

If you need documentation for any of the nested job structs, the QueryFlags enum, or the PreCullingData/ CullingInfo data layouts referenced by this system, tell me which item and I will add a focused section.