CNA-BUG-025: PlaneIntersectionType's Doxygen swaps the meaning of Front and Back

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

PlaneIntersectionType.hpp documents Front as the negative half-space and Back as the positive one, the opposite of what every CNA classification returns and of XNA's meaning.

Identifier

CNA-BUG-025

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

Microsoft::Xna::Framework::PlaneIntersectionType (Front, Back) as documented in its public header

Expected behaviour

Front means the whole volume lies in the positive half-space, the side the plane normal points to (Dot(Normal, p) + D > 0); Back means the negative half-space. That is what XNA 4.0 returns: its Plane.Intersects(ref BoundingSphere, out PlaneIntersectionType) answers Front when the signed centre distance exceeds the radius (read from the IL of the genuine XNA 4.0 Microsoft.Xna.Framework assembly; not executed).

Actual behaviour at TARGET

The comments in PlaneIntersectionType.hpp say Front is "in the negative half-space of the plane" and Back "in the positive half-space". Every implementation does the opposite: Plane::IntersectsPoint returns Front for a positive distance, BoundingSphere::Intersects(const Plane&, PlaneIntersectionType&) returns Front when the distance exceeds the radius, BoundingBox::Intersects(const Plane&, PlaneIntersectionType&) returns Front when even the box's most negative vertex is on the positive side, and BoundingFrustum::Intersects(const Plane&, PlaneIntersectionType&) builds on IntersectsPoint. The comment text is FNA's, which carries the same inverted wording. A reader who follows the header inverts a culling or classification test.

Source locations

• modules/math/include/Microsoft/Xna/Framework/PlaneIntersectionType.hpp — the Front and Back Doxygen comments
• modules/math/src/Plane.cpp — Plane::IntersectsPoint: Front for distance > 0
• modules/math/src/BoundingSphere.cpp — BoundingSphere::Intersects(const Plane&, PlaneIntersectionType&)
• modules/math/src/BoundingBox.cpp — BoundingBox::Intersects(const Plane&, PlaneIntersectionType&)
• modules/math/tests/Microsoft/Xna/Framework/PlaneIntersectionTypeTests.cpp — checks only distinctness and the XNA ordinals
• modules/c-api/tests/pure_c/GeometrySmoke.c — validate_plane: a box below the ground plane is BACK, a sphere above it FRONT

Evidence

Checked by reading at 009d40f5; nothing was built or executed for this entry. The contradiction is between the header text and four function bodies; the C ABI smoke test GeometrySmoke.c pins the implemented meaning (FRONT for a sphere above the plane y = 0 whose normal points up). XNA's meaning was read from its IL.

Focused reproduction

Illustrative; not compiled or run for this entry.

Plane ground(Vector3(0.0f, 1.0f, 0.0f), 0.0f);                          // normal points up
PlaneIntersectionType t = ground.Intersects(BoundingSphere(Vector3(0.0f, 5.0f, 0.0f), 1.0f));
// t == PlaneIntersectionType::Front: the sphere is in the POSITIVE half-space,
// although the header comment on Front says "negative".

Current tests

PlaneIntersectionTypeTests.cpp checks that the three values are distinct and have the XNA ordinals 0, 1 and 2. The implemented meaning is pinned by GeometrySmoke.c and by the plane cases of the bounding-volume suites; nothing checks documentation.

Regression test

A documentation fix (swap the two comments to XNA's wording). The existing semantic tests already pin the behaviour; a one-line unit test named for the convention (a sphere on the normal's side is Front) would make the intent explicit.

Blast radius

Documentation only: the public header, generated API documentation and IDE tooltips. No behaviour changes, and the C ABI enum identities (CNA_PLANE_INTERSECTION_*) are unaffected.

Workaround

Rely on the implementation: Front means entirely on the side the plane normal points to.