fix(graphics): honour RFX_TILE_DIFFERENCE in Progressive decode

[Yevhen Salitrynskyi (ysalitrynskyi)]

Problem

The Progressive RemoteFX decoder parses the tile flags byte on TILE_SIMPLE and TILE_FIRST blocks, but nothing ever consumes it. TileState::decode_first unconditionally set self.is_difference = false, and no coefficient path read that field, so a tile flagged RFX_TILE_DIFFERENCE (0x01) was decoded as if it carried absolute coefficients.

The delta is then rendered as if it were the image, and every later progressive upgrade pass refines the wrong coefficients, so the error compounds across the frame.

Spec

MS-RDPEGFX sections 2.2.4.2.1.5.3 (RFX_PROGRESSIVE_TILE_SIMPLE) and 2.2.4.2.1.5.4 (RFX_PROGRESSIVE_TILE_FIRST) define the flag:

RFX_TILE_DIFFERENCE 0x01 — Indicates that the tile contains the compressed difference of the DWT coefficients for the same tile between the current frame and the previous frame.

Section 3.3.8.2.1.1 gives the decode rule:

If the tile is a difference tile (section 3.1.8.1.2), then the progressively quantized coefficients are simply added to the DecDwtQ elements:
DecDwtQ = DecDwtQ + DecProgQ * PQF

and section 3.3.8.2.1 states the complementary rule for original tiles — the tile is zeroed in the current frame first, and the entropy decode result is added to it.

The same section requires the LL3 deltas to be summed up "even if the tile is not an original tile", so the LL3 differential decode stays unconditional. FreeRDP's progressive_decompress behaves the same way (progressive_rfx_dwt_2d_decode adds the freshly decoded buffer into the persisted current buffer, saturating at the INT16 bounds, when coeffDiff is set).

Changes

ironrdp-pdu — crates/ironrdp-pdu/src/codecs/rfx/progressive.rs

• Add FLAG_TILE_DIFFERENCE and is_difference() accessors on TileSimple and TileFirst, following the existing FLAG_DWT_REDUCE_EXTRAPOLATE / uses_reduce_extrapolate() pattern. The seven high bits of the flags field remain reserved and ignored, as the spec requires.

ironrdp-graphics — crates/ironrdp-graphics/src/progressive.rs

• Add TileState::decode_first_difference, which decodes the three components into a scratch buffer and accumulates them into the retained coefficients, saturating at the i16 bounds. The accumulation happens in the DecDwtQ domain — before base dequantization and the inverse DWT — which is where both the retained coefficients and the incoming differences live.
• decode_tile_block routes TILE_SIMPLE and TILE_FIRST to that path when the flag is set, and to the existing path otherwise.
• The shared first-pass bookkeeping moves into a private begin_first_pass, and is_difference now records how the most recent first-pass tile was encoded instead of being hardcoded to false.

Notes on the semantics:

• DAS sign state keeps describing the incoming differences rather than the accumulated result, because that is what the upgrade passes refining this transmission are encoded against. This matches both the spec (section 3.3.8.2.1.1 derives the tri-state from DecProgQ) and FreeRDP, which fills its sign buffer from the freshly RLGR-decoded data regardless of the flag.
• Unusable reference: the retained coefficients stay base-quantized until reconstruction, so they only mean anything while the base quantization tables and the DWT variant hold. If a stream changes either, the reference is dropped and the tile decodes as an original one. Without that, a difference tile carrying an all-zero delta corrupted most of the tile. The spec does not define the case; degrading one tile beats erroring out the whole frame.
• First tile of a surface: a tile that has not been decoded yet holds zeroed coefficients, so a difference tile arriving first reconstructs to the same values as an absolute one. No special case is needed, and there is a test for it.
• Upgrade passes: TILE_UPGRADE has no flags field on the wire, and it already accumulates into the retained coefficients, so it is unaffected. FreeRDP reads tile->flags in its upgrade path but the value is unused there, since it copies the persisted buffer into the DWT buffer regardless.

No public API break. decode_first keeps its signature and its behaviour for original tiles; the difference path is a new method.

No new dependencies.

Tests

ironrdp-graphics:

• difference_tile_accumulates_into_retained_coefficients — an absolute tile followed by a flagged one; asserts the full 4096-coefficient buffer of all three components equals retained + newly decoded, and that the DAS state describes the incoming differences.
• non_difference_tile_replaces_retained_coefficients — two absolute tiles in a row still replace, and the result is identical to decoding the second one on a fresh tile.
• difference_tile_on_untouched_tile_matches_absolute_tile — first tile of a surface.
• difference_tile_accumulation_saturates — accumulation clamps at the i16 bounds.
• upgrade_pass_refines_accumulated_difference_coefficients — an upgrade pass after a difference tile refines the accumulated coefficients.
• decoder_accumulates_difference_tiles_signalled_on_the_wire — end-to-end through ProgressiveDecoder::decode_bitmap, driven by the real flags byte: a flagged tile renders pixel-identical to a single absolute tile carrying the summed coefficients, an unflagged one renders identically to decoding it standalone, and the two differ.

ironrdp-pdu: tile_difference_flag_survives_round_trip and tile_first_difference_flag_survives_round_trip cover the flags byte and the reserved high bits.

The fixtures are built with the crate's existing rlgr::encode helper, the same approach as the surrounding progressive tests; there were no captured progressive fixtures in the repo to reuse.

Each new test was checked against a deliberately broken build (accumulation reverted to replacement, and the wire dispatch forced to the absolute path) to confirm it fails without the fix.

Verification

cargo xtask check fmt -v      # All good!
cargo xtask check lints -v    # All good!
cargo xtask check tests -v    # All good!
cargo xtask check typos -v    # All good!
cargo xtask check locks -v    # All good!

cargo test -p ironrdp-graphics -p ironrdp-pdu: 217 passed / 0 failed, 412 passed / 0 failed.

Additional tests cover TILE_FIRST end to end, the reduce-extrapolate band layout, and a difference tile arriving after an upgrade pass. Each new test was checked against a deliberately broken build to confirm it fails without the fix.

Overlap and known gaps

• fix(graphics): retain Progressive difference tiles #1698 covers the same bug and models the retained state better: it keys the sub-band diffing reference by surface and keeps it across ResetGraphics, per MS-RDPEGFX 3.3.1.3. This PR reuses TileState::coefficients, which is keyed by (surface_id, codec_context_id), so RDPGFX_DELETE_ENCODING_CONTEXT drops the reference that 3.3.1.3 says must survive. Maintainers should take whichever base they prefer; the tests here apply to both.
• Not validated against a captured difference-encoded frame; the correctness argument rests on the spec text and on matching FreeRDP.
• Separately, use_reduce_extrapolate is read from the CONTEXT block, where bit 0 is RFX_SUBBAND_DIFFING (2.2.4.2.1.4). RFX_DWT_REDUCE_EXTRAPOLATE is a REGION flag (2.2.4.2.1.5), and ProgressiveRegion::uses_reduce_extrapolate() is currently dead code. Pre-existing and out of scope here.

Refs #1240

[Marc-André Moreau (mamoreau-devolutions)]

Yevhen Salitrynskyi (@ysalitrynskyi) I think you found the same thing I found while replaying packet captures taken with mstsc in IronRDP, I've got this pull request here: #1701

[Yevhen Salitrynskyi (ysalitrynskyi)]

Yes, same bug. You got there first with #1698, and its model is the right one: the sub-band diffing reference belongs to the surface and survives ResetGraphics, while mine reuses the per-codec-context tile state. Left the review on #1698, and the tests here apply to either base.

[Copilot]

Pull request overview

Adds decoding support for Progressive RemoteFX difference tiles.

Changes:

• Exposes and parses RFX_TILE_DIFFERENCE.
• Accumulates decoded coefficient deltas with saturation.
• Adds unit and end-to-end coverage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
crates/ironrdp-pdu/src/codecs/rfx/progressive.rs	Adds difference-flag accessors and tests.
crates/ironrdp-graphics/src/progressive.rs	Implements difference accumulation and decoding tests.