Struct ScyllaAABB3

Blittable 3D axis-aligned bounding box (AABB) optimized for Burst compilation and DOTS contexts.

Implements

IEquatable<ScyllaAABB3>

Inherited Members

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Structures

Assembly: ScyllaCore.dll

Syntax

[BurstCompile]
public struct ScyllaAABB3 : IEquatable<ScyllaAABB3>

Remarks

An AABB is defined by two corner points (Min and Max) representing the smallest box aligned with the world coordinate axes that contains a given object or set of points.

Key Characteristics:

Axis-aligned: box edges are parallel to the X, Y, and Z axes (no rotation).
Efficient: overlap tests and ray intersections use simple min/max comparisons.
Blittable: contains only primitive types; safe for Burst compilation and native memory.
Immutable operations: methods return new instances rather than modifying in place.

Common Use Cases:

Broad-phase collision detection in ScyllaBVH and ScyllaLooseOctreeCore.
Frustum culling and visibility tests.
Spatial partitioning and region queries via ScyllaLooseOctreeCore.
Conservative bounds for complex geometry.

Validity:

A valid AABB has Max >= Min on all axes. Invalid AABBs (where Max < Min on any axis) represent empty or degenerate volumes and will fail IsValid checks.

Performance Notes:

All operations are designed for SIMD optimization via Unity.Mathematics.
Compatible with the Burst compiler for maximum performance in jobs.
Zero managed allocations (struct with value semantics).

For 2D broad-phase work, use ScyllaAABB2 instead. For ray construction with automatic inverse-direction computation, see ScyllaRay3.

Constructors

ScyllaAABB3(float3, float3)

Creates a new ScyllaAABB3 from explicit minimum and maximum corner points.

Declaration

public ScyllaAABB3(float3 min, float3 max)

Parameters

Type	Name	Description
float3	min	Minimum corner (smallest X, Y, and Z coordinates). For a valid AABB this must be component-wise less than or equal to `max`.
float3	max	Maximum corner (largest X, Y, and Z coordinates). For a valid AABB this must be component-wise greater than or equal to `min`.

Remarks

This constructor assigns the corners directly without validation. The caller is responsible for ensuring max >= min on all axes for a valid AABB. Use IsValid to verify the result if the inputs are not known to be well-ordered.

Fields

Max

Maximum corner of the AABB (largest X, Y, and Z coordinates of the enclosed volume).

Declaration

public float3 Max

Field Value

Type	Description
float3

Remarks

For a valid AABB, Max must be greater than or equal to Min on all axes. This point represents the corner of the box with the largest coordinate values in world space.

Min

Minimum corner of the AABB (smallest X, Y, and Z coordinates of the enclosed volume).

Declaration

public float3 Min

Field Value

Type	Description
float3

Remarks

For a valid AABB, Min must be less than or equal to Max on all axes. This point represents the corner of the box with the smallest coordinate values in world space.

Properties

Center

Gets the center point of the AABB (the midpoint between Min and Max).

Declaration

public float3 Center { get; }

Property Value

Type	Description
float3	The center point, computed as `(Min + Max) * 0.5`. For a degenerate or invalid AABB, this still returns the midpoint of the corner values.

HalfSize

Gets the half-size (extents) of the AABB along each axis.

Declaration

public float3 HalfSize { get; }

Property Value

Type	Description
float3	Half the full size, computed as `(Max - Min) * 0.5`. This represents the distance from the center to the edge along each axis. Commonly used with FromCenterHalfSize(float3, float3) when constructing AABBs from center/extent representations.

IsValid

Gets a value indicating whether this AABB is well-formed.

Declaration

public bool IsValid { get; }

Property Value

Type	Description
bool	`true` if `Max >= Min` on all axes; `false` if `Max < Min` on any axis, which indicates an empty, degenerate, or incorrectly constructed bounding box.

Remarks

Degenerate AABBs (where Min == Max on one or more axes) are considered valid: they represent zero-volume planes, lines, or points, which are geometrically meaningful. Only AABBs where Max < Min on any axis are considered invalid.

Size

Gets the full size of the AABB along each axis (width, height, and depth).

Declaration

public float3 Size { get; }

Property Value

Type	Description
float3	The full dimensions, computed as `Max - Min`. All components are non-negative for a valid AABB. For an invalid AABB (`Max < Min`), one or more components will be negative.

SurfaceArea

Gets the total surface area of the AABB.

Declaration

public float SurfaceArea { get; }

Property Value

Type	Description
float	The surface area, computed as `2 * (width * height + width * depth + height * depth)`. Returns `0` for degenerate AABBs with zero volume (e.g., a flat slab). For invalid AABBs where `Max < Min`, the result is undefined (likely negative).

Remarks

This is a critical metric for ScyllaBVH construction using the Surface Area Heuristic (SAH). SAH assumes that the probability of a ray hitting a bounding volume is proportional to its surface area, making surface area an excellent cost proxy for tree quality when choosing optimal split points.

Common uses:

BVH construction: choosing optimal split positions for internal nodes.
Quality metrics for spatial data structures.
Cost estimation for ray tracing traversal.

Methods

Contains(ScyllaAABB3)

Determines whether this AABB fully contains another AABB.

Declaration

public bool Contains(ScyllaAABB3 other)

Parameters

Type	Name	Description
ScyllaAABB3	other	The AABB to test for containment within this AABB.

Returns

Type	Description
bool	`true` if this AABB fully contains `other`, including touching boundaries; `false` if any part of `other` lies outside this AABB.

Remarks

Containment is satisfied when every point in other lies inside or on the boundary of this AABB. This requires:

this.Min <= other.Min on all axes (the other's minimum corner is inside this).
this.Max >= other.Max on all axes (the other's maximum corner is inside this).

Edge cases:

AABBs that share a boundary (face, edge, or corner) are considered contained (inclusive test).
An AABB always contains itself.
Degenerate (zero-volume) AABBs can still contain other degenerate AABBs at the same position.

DistanceSqToPoint(float3)

Computes the squared distance from a point to the nearest point on or inside this AABB.

Declaration

public float DistanceSqToPoint(float3 point)

Parameters

Type	Name	Description
float3	point	The 3D point to measure from.

Returns

Type	Description
float	The squared distance from `point` to the nearest point on or inside this AABB. Returns `0` if the point is inside or on the surface of the AABB.

Remarks

For each axis the per-axis distance component is computed as:

If the point lies below Min: component = Min - point.
If the point lies above Max: component = point - Max.
If the point lies between Min and Max: component = 0.

The squared distance is the sum of the squared per-axis components.

Common Use Cases:

Sphere-vs-AABB test: a sphere overlaps this AABB if DistanceSqToPoint(center) <= radius * radius.
Nearest-neighbor priority ordering during ScyllaBVH traversal.
Range queries: find all AABBs within distance D of a point by testing distanceSq <= D * D.

Working with squared distance avoids the expensive square root operation; only take the root when an actual distance value is required.

Equals(ScyllaAABB3)

Tests exact equality between this ScyllaAABB3 and another.

Declaration

public bool Equals(ScyllaAABB3 other)

Parameters

Type	Name	Description
ScyllaAABB3	other	The ScyllaAABB3 to compare with this instance.

Returns

Type	Description
bool	`true` if both Min and Max corners are exactly equal; `false` otherwise.

Remarks

Two AABBs are equal if and only if both their Min and Max corners are exactly equal (component-wise floating-point equality). This is a strict equality test with no epsilon tolerance. For approximate equality with floating-point tolerance, implement a custom comparison using NumberUtil.Approximately.

Note: this equality test considers AABBs with identical but invalid bounds (e.g., both have Max < Min) as equal.

Equals(object)

Tests exact equality between this ScyllaAABB3 and a boxed object.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare with this instance.

Returns

Type	Description
bool	`true` if `obj` is a ScyllaAABB3 with equal bounds; `false` otherwise.

Overrides

ValueType.Equals(object)

Remarks

Returns true only if obj is a ScyllaAABB3 with exactly equal Min and Max corners. Returns false if obj is null or not a ScyllaAABB3.

Expanded(float)

Returns a new ScyllaAABB3 expanded uniformly by margin in every direction.

Declaration

public ScyllaAABB3 Expanded(float margin)

Parameters

Type	Name	Description
float	margin	The uniform amount to expand in each direction. Values less than or equal to zero return `this` unmodified.

Returns

Type	Description
ScyllaAABB3	A new ScyllaAABB3 with Min decreased and Max increased by `margin` on every axis, or `this` if `margin` is non-positive.

Remarks

The expanded AABB is computed as:

Min -= margin on all axes.
Max += margin on all axes.

If margin is less than or equal to zero, this is returned unchanged (no allocation occurs).

A common pattern is to store a "fat" AABB (this AABB plus a small margin) alongside the tight AABB in a ScyllaBVH or ScyllaLooseOctreeCore. When an object moves, its updated tight AABB is compared against the fat AABB; as long as the tight bounds remain inside the fat bounds, the tree does not need to be updated, reducing reinsertion churn for frequently-moving objects.

FromCenterHalfSize(float3, float3)

Creates a ScyllaAABB3 from a center point and a half-size (extents) vector.

Declaration

public static ScyllaAABB3 FromCenterHalfSize(float3 center, float3 halfSize)

Parameters

Type	Name	Description
float3	center	Center point of the new AABB in world space.
float3	halfSize	Half the size of the AABB along each axis (the extents). All components should be non-negative for a valid result.

Returns

Type	Description
ScyllaAABB3	A new ScyllaAABB3 centered at `center` with the given extents.

Remarks

This is a convenient alternative to the min/max constructor when the center and extents of the bounding box are known. The resulting AABB is computed as:

Min = center - halfSize
Max = center + halfSize

halfSize should have non-negative components. Negative components will produce an invalid AABB where Max < Min on the corresponding axis.

See also FromCenterHalfSize(float2, float2) for the 2D equivalent.

GetHashCode()

Computes a hash code for this ScyllaAABB3.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A 32-bit signed integer hash code suitable for use in hash tables and dictionaries.

Overrides

ValueType.GetHashCode()

Remarks

The hash code is derived by combining the hash codes of Min and Max using a prime-number multiplication chain (initial value 17, multiplier 31). The unchecked block allows integer overflow, which is intentional and safe for hash code computation. AABBs with equal Min and Max corners are guaranteed to produce the same hash code.

Overlaps(ScyllaAABB3)

Determines whether this AABB overlaps or touches another AABB.

Declaration

public bool Overlaps(ScyllaAABB3 other)

Parameters

Type	Name	Description
ScyllaAABB3	other	The AABB to test for overlap with this AABB.

Returns

Type	Description
bool	`true` if the AABBs overlap or touch; `false` if they are completely separated.

Remarks

The overlap test uses the separating axis theorem: two AABBs overlap when they are NOT separated along any axis. The test checks that:

this.Min <= other.Max on all axes (this starts before or where other ends).
this.Max >= other.Min on all axes (this ends after or where other starts).

This is an inclusive test:

AABBs that share only a boundary (face, edge, or corner) are considered overlapping.
Degenerate (zero-volume) AABBs can overlap at a single point or along a line.
The test is symmetric: A.Overlaps(B) == B.Overlaps(A).

Performance: this is an extremely fast test (6 comparisons and a logical AND). It is the primary broad-phase test used by ScyllaLooseOctreeCore and ScyllaBVH.

RayIntersects(float3, float3, float, float)

Tests whether a 3D ray intersects this AABB using the efficient slab method.

Declaration

public bool RayIntersects(float3 origin, float3 invDir, float tMin, float tMax)

Parameters

Type	Name	Description
float3	origin	The 3D origin point of the ray.
float3	invDir	The component-wise reciprocal of the ray direction (`1/dir` per axis). Near-zero direction components should be represented as `float.PositiveInfinity`. See ScyllaRay3 for automatic computation.
float	tMin	The minimum ray parameter defining the start of the segment to test. Use `0` to start at the ray origin.
float	tMax	The maximum ray parameter defining the end of the segment to test. Use `float.PositiveInfinity` for an unbounded ray.

Returns

Type	Description
bool	`true` if the ray intersects this AABB within the parameter range [`tMin`, `tMax`]; `false` otherwise.

Remarks

The slab method treats the AABB as the intersection of three axis-aligned slabs (one per axis). For each axis it computes where the ray enters and exits that slab, then finds the overall intersection interval across all three axes.

Algorithm:

For each axis, compute entry distance t1 and exit distance t2 using (corner - origin) * invDir.
Find the maximum entry distance across all axes (the last slab entered).
Find the minimum exit distance across all axes (the first slab exited).
The ray intersects if exit >= enter.

Inverse Direction:

invDir must be the component-wise reciprocal (1 / direction) of the ray direction. Precomputing this value outside the test avoids division per axis during traversal. Use ScyllaRay3 to construct a ray with the inverse direction precomputed and with correct handling of near-zero components (which become float.PositiveInfinity).

Ray Parameter Range:

tMin: start of the ray segment to test (typically 0 for a ray from its origin).
tMax: end of the ray segment to test (use float.PositiveInfinity for an infinite ray).
A point at parameter t lies at origin + t * direction.

Union(ScyllaAABB3, ScyllaAABB3)

Computes the union of two AABBs, returning the smallest AABB that fully contains both.

Declaration

public static ScyllaAABB3 Union(ScyllaAABB3 a, ScyllaAABB3 b)

Parameters

Type	Name	Description
ScyllaAABB3	a	The first AABB.
ScyllaAABB3	b	The second AABB.

Returns

Type	Description
ScyllaAABB3	The smallest ScyllaAABB3 that fully contains both `a` and `b`.

Remarks

The union is computed by taking:

Min = component-wise minimum of both AABBs' Min corners.
Max = component-wise maximum of both AABBs' Max corners.

This operation is:

Commutative: Union(A, B) == Union(B, A).
Associative: Union(Union(A, B), C) == Union(A, Union(B, C)).
Always produces a valid AABB when both inputs are valid.

Common uses:

Building ScyllaBVH internal node bounds from child leaf bounds.
Computing aggregate bounds for a collection of objects.
Expanding an AABB to include additional geometry.

Operators

operator ==(ScyllaAABB3, ScyllaAABB3)

Returns true if two ScyllaAABB3 instances have exactly equal Min and Max corners.

Declaration

public static bool operator ==(ScyllaAABB3 a, ScyllaAABB3 b)

Parameters

Type	Name	Description
ScyllaAABB3	a	The first AABB to compare.
ScyllaAABB3	b	The second AABB to compare.

Returns

Type	Description
bool	`true` if `a` and `b` are exactly equal; `false` otherwise.

operator !=(ScyllaAABB3, ScyllaAABB3)

Returns true if two ScyllaAABB3 instances have different Min or Max corners.

Declaration

public static bool operator !=(ScyllaAABB3 a, ScyllaAABB3 b)

Parameters

Type	Name	Description
ScyllaAABB3	a	The first AABB to compare.
ScyllaAABB3	b	The second AABB to compare.

Returns

Type	Description
bool	`true` if `a` and `b` are not exactly equal; `false` otherwise.

Implements

IEquatable<T>