CNA-BUG-248: PacketWriter::Write(Color)'s doc comment still says ReadColor reads four floats and is not the inverse of Write(Color)

CNA snapshot 3b43bd86  ·  Known Issues › Current bugs  ·  source links pinned to 3b43bd86

ReadColor reads the four bytes Write(Color) writes, a test asserts the round trip, and ReadColor's own header comment now says so, but PacketWriter.hpp still describes a four-float asymmetry preserved from 'upstream', which XNA 4.0 does not have.

Identifier

CNA-BUG-248

Category

Bug

Subsystem

Documentation & release tooling

Status

Narrowed (partially fixed; describes only what survives)

Verified against

CNA 3b43bd86 (3b43bd8687ed46523d873f9bec4b32bd8481dcb5)

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::Net::PacketReader::ReadColor() and PacketWriter::Write(Color) Doxygen

Expected behaviour

The public header documentation describes the implemented wire format: Write(Color) writes R, G, B, A as four bytes and ReadColor() reads them back, so the two are inverses. XNA 4.0 agrees: its PacketWriter.Write(Color) writes Color.PackedValue as a uint and PacketReader.ReadColor() reads a uint into PackedValue (IL of Microsoft.Xna.Framework.Net).

Actual behaviour at TARGET

PacketReader.cpp reads four bytes, with a comment explaining the 2026-09-04 correction (c4561fd2b), PacketReaderTest.ReadColorReadsFourBytesAndInvertsWriteColor asserts the round trip, and PacketReader.hpp now documents ReadColor as the inverse of Write(Color). Yet PacketWriter.hpp still says Write(Color) is “Not the inverse of PacketReader::ReadColor(), which reads four floats: the upstream implementation writes bytes here and reads floats there. Preserved as-is for behavioral fidelity rather than symmetrized.”

Source locations

• modules/net/include/Microsoft/Xna/Framework/Net/PacketWriter.hpp — Write(Color) doc comment: not the inverse of ReadColor
• modules/net/include/Microsoft/Xna/Framework/Net/PacketReader.hpp — ReadColor doc comment: the inverse of Write(Color) (the fixed half)
• modules/net/src/Xna/PacketReader.cpp — PacketReader::ReadColor reads four bytes
• modules/net/tests/Microsoft/Xna/Framework/Net/PacketReaderWriterTests.cpp — WriteColorWritesFourBytes; ReadColorReadsFourBytesAndInvertsWriteColor

Evidence

Checked by reading at 3b43bd86; not executed. The XNA 4.0 contract was checked in the IL disassembly of Microsoft.Xna.Framework.Net (PacketReader::ReadColor calls BinaryReader::ReadUInt32 and Color::set_PackedValue; PacketWriter::Write(Color) writes get_PackedValue through BinaryWriter::Write(uint32)), so the header's “upstream” asymmetry is not XNA's behaviour either. Header drift, not a behaviour defect.

Narrowed at c6dec91f: 66918da04 (2026-10-19) corrected ReadColor's comment in PacketReader.hpp, the block comment in PacketReaderWriterTests.cpp (now “share the four-byte RGBA layout”) and the demo_packet_roundtrip example, which now checks the inverse; the comment on Write(Color) was left as it was.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

PacketWriterTest.WriteColorWritesFourBytes and PacketReaderTest.ReadColorReadsFourBytesAndInvertsWriteColor pin the corrected behaviour; nothing checks the comments.

Regression test

Documentation fix: both Doxygen blocks should say four bytes, R, G, B, A, inverse of each other, matching XNA's packed value; delete the stale block comment in the test file.

Blast radius

Users of the networking API reading the public headers, who would expect ReadColor to consume sixteen bytes and might write four floats to feed it, which now misreads the packet. No runtime behaviour is affected.

Workaround

Treat Write(Color)/ReadColor() as a four-byte round trip, as the implementation and the packet notes describe.