CNA-BUG-248: PacketReader::ReadColor and PacketWriter::Write(Color) doc comments still say ReadColor reads four floats and is not the inverse of Write(Color)

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

Since c4561fd2b ReadColor reads the four bytes Write(Color) writes and a test asserts the round trip, but both public header comments and a test-file comment still describe a four-float asymmetry preserved from 'upstream', which XNA 4.0 itself does not have.

Identifier

CNA-BUG-248

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::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), and PacketReaderTest.ReadColorReadsFourBytesAndInvertsWriteColor asserts the round trip. Yet PacketReader.hpp still documents ReadColor as 'Reads a Color value as four 32-bit floats' and 'Not the inverse of PacketWriter::Write(Color) ... Preserved as-is for behavioral fidelity', PacketWriter.hpp says Write(Color) is 'Not the inverse of PacketReader::ReadColor(), which reads four floats', and the block comment above WriteColorWritesFourBytes in PacketReaderWriterTests.cpp says ReadColor reads 4 floats and Color is not round-trippable, directly above the test that proves the opposite. The example Main.cpp carries the same claim: a 'deliberately mismatched pairing' block calls the four-float read a documented upstream quirk and expects ReadColor() to throw, then reports the now-successful read as a QUIRK row that still counts as a pass.

Source locations

• modules/net/include/Microsoft/Xna/Framework/Net/PacketReader.hpp — ReadColor doc comment
• modules/net/include/Microsoft/Xna/Framework/Net/PacketWriter.hpp — Write(Color) doc comment
• modules/net/src/Xna/PacketReader.cpp — PacketReader::ReadColor reads four bytes
• modules/net/tests/Microsoft/Xna/Framework/Net/PacketReaderWriterTests.cpp — stale block comment above WriteColorWritesFourBytes; ReadColorReadsFourBytesAndInvertsWriteColor

Evidence

Checked by reading at 009d40f5; 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 headers' “upstream” asymmetry is not XNA's behaviour either. Header and test-comment drift, not a behaviour defect.

Independent re-verification: Checked by reading at 009d40f5; not executed. The XNA 4.0 contract was checked in the decompiled Microsoft.Xna.Framework.Net (PacketReader.ReadColor sets PackedValue from ReadUInt32; PacketWriter.Write(Color) writes PackedValue as a uint), so the 'upstream' asymmetry in the comments is not XNA's behaviour either. Correction to the earlier scope: the same stale statement also survives in the demo_packet_roundtrip example, which the suggested documentation fix would not touch. Header, test-comment and example drift, not a behaviour defect.

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.