11 KiB
test_paint_stream
Type: Reusable API. Source contract: test_paint_stream.h.
Use when
A campaign claims what one opaque widget's whole paint costs, for example
"smooth while animating or dragging". Debug Telegram links Debug Qt, so a
paint timed inside it is not a paint cost. This header records the real owner
into an in-memory QPicture per sample from the overlay, saves each stream
with format-preserving sidecars and writes a manifest; the shared
paint replay recipe
replays the streams in optimized Qt behind the
native execution gate
and judges them. For a picture of what was painted use
test_capture; for frames at chosen animation times use
test_animation_clock.
Preconditions and limits
- An opaque owner whose own
paintEventpaints the measured surface.RecordPaint's default flags,QWidget::RenderFlags(), record what the backing store paints for a child owner: itspaintEvent, plus itsautoFillBackgroundfill or styled background, without children. A translucent child therefore leaves device pixels uncovered, and the assessor refuses it asnot-whole-owner. PassQWidget::DrawWindowBackgroundonly for a top-level window owner: Qt then fills the palette'sWindowbrush under an owner that sets neitherQt::WA_OpaquePaintEventnorQt::WA_NoSystemBackground, as the window's own paint does. That fill is part of the stream and its timed cost, and it covers the surface whatever the owner paints. For a child it is a paint the screen never runs, so it would hide a translucent owner and inflate the cost. PassQWidget::DrawChildrenfor an owner that paints through children. - Images keep their recorded row stride: an image over an external buffer with padded rows, such as an FFmpeg frame with 64-byte rows, replays from that layout.
- macOS only, and Qt's private
QtGui/private/qpicture_p.h(GuiPrivate): the header stops with#erroron another platform or without it, and aDESKTOP_APP_DISABLE_PRIVATE_QT_APIbuild cannot use it.QPicturePrivateis private API: the recorder and the replayer must report the same exactqVersion(), picture format and sidecar version. - The replayer runs under the recorded platform plugin and color scheme
(
PaintQtIdentity()writes both into the manifest) and refuses another one: cocoa draws grayscale-smoothed glyphs differently in Dark and Light. A session whose appearance changed after recording must be replayed in the recorded appearance or recorded again. - A stream stores text, its font and flags, not glyphs: text items are laid
out again at replay. The replay needs every font file the owner uses, and an
owner whose text replays differently from its direct render fails
recording-not-faithful. PaintSurface::rootTypeis the literal demangled type the author writes down (PaintTypeName()returns that form for a live widget); it is never read from the recorded widget, so a wrong root is refused aswrong-paint-rootinstead of adopted.sizeis the owner's logical size anddprthe device pixel ratio of every replay target.- Record inside the timed window and save after it:
RecordPainttimes only the painter session aroundQWidget::render(), whileSavePaintRecordingencodes, writes, reads back, replays and digests.PaintDirectDifferencerenders the owner a second time and replays the stream, so call it on a few samples whose cadence the claim does not depend on, right after theirRecordPaintand before the owner's state changes. - A region recording keeps the region's bounding rectangle clipped to the owner, at its own position, and clips the picture painter to it.
- Stream names use letters, digits,
_,.and-, so a stream file never leaves the run directory. Caller fields must not reuse a row key (name,role,recordMs,root,qpic,tables,counts,fonts,referenceSha256,directDifference). - Never
load()orsetData()a recording or a copy sharing it: both detach through a private copy that dropsin_memory_only, the format version and the four lists. Copies used forsave()andplay()are safe. - Streams and sidecars hold painted pixels, in a real session account content: keep them in the ignored run directory and never promote them; promote the assessment JSON only.
- The header establishes no timing claim by itself.
recordMsmeasured in Debug Telegram is a Debug-Qt CPU cost of emitting the stream (conservative); the replay supplies the optimized raster cost of the same stream. Neither is a Release Telegram frame time or a compositor cadence.
Minimal use
An overlay sketch against the real API; owner is the exact live widget the
overlay resolved, and the field hiding is the campaign's own owner-specific
step. The same calls are compiled and run by the component fixture
.agents/shared/evidence/paint_replay_component/fixture.cpp; no Telegram
translation unit compiles this snippet.
#include "test/test_log.h"
#include "test/test_paint_stream.h"
auto surface = Test::PaintSurface();
surface.rootType = u"Example::Owner"_q; // literal, never PaintTypeName(owner)
surface.size = owner->size();
surface.dpr = owner->devicePixelRatio();
auto recordings = std::vector<Test::PaintRecording>();
// Inside each timed window ("rest", "drag", "glide"), once per sample.
auto recording = Test::RecordPaint(
owner,
u"%1_%2"_q.arg(window).arg(index),
u"timed"_q,
QJsonObject{
{ u"window"_q, window },
{ u"at"_q, double(crl::now()) },
{ u"pressed"_q, pressed },
{ u"moving"_q, moving },
{ u"position"_q, QJsonArray{ position.x(), position.y() } },
});
if (window == u"rest"_q && !index) {
recording.directDifference = Test::PaintDirectDifference(
owner,
recording,
surface);
}
recordings.push_back(std::move(recording));
// After the window, with the owner back in the state of "rest_0".
hideMeasuredField(owner);
recordings.push_back(Test::RecordPaint(
owner,
u"absent_0"_q,
u"absent"_q,
QJsonObject{
{ u"pairedWith"_q, u"rest_0"_q },
{ u"fieldRect"_q, QJsonArray{ 16, 16, 64, 64 } },
}));
showMeasuredField(owner);
recordings.push_back(Test::RecordPaint(
owner,
u"narrow_0"_q,
u"narrow"_q,
QJsonObject(),
QRegion(0, 0, 24, owner->height())));
recordings.push_back(Test::EmptyPaintRecording(u"empty_0"_q));
const auto dir = QDir(Test::EvidenceDir()).filePath(u"paint"_q);
auto rows = QJsonArray();
for (const auto &recording : recordings) {
auto error = QString();
rows.push_back(
Test::SavePaintRecording(dir, recording, surface, &error));
Test::Check(error.isEmpty(), u"saved "_q + recording.name, error);
}
auto error = QString();
Test::Check(
Test::WritePaintManifest(dir, surface, rows, &error),
u"paint manifest"_q,
error);
Roles are timed (whole-owner samples the timing and the window judgement
read), absent (the paired state without the measured field, with its
owner-logical fieldRect), narrow (a region smaller than the owner, which
must not pass as whole) and empty. Any other role, such as a "baseline", is
refused by the assessor.
Readings and refusals
SavePaintRecording returns the manifest row: name, role, recordMs,
root {type, size [w, h], region [x, y, w, h], flags}, qpic and tables
{file, bytes, sha256}, counts {images, pixmaps, brushes, pens}, fonts
(sorted {family, resolved}), referenceSha256 (the recorder-side replay
over sentinel 0), directDifference when measured, then the caller's fields.
On failure it returns an empty object and sets *error to <code>: <detail>
with code invalid-stream-name, reserved-field-key,
not-in-memory-picture, cannot-create-directory, invalid-surface,
stream-save-failed, sidecar-write-failed, write-failed,
write-verify-failed or reference-playback-failed.
WritePaintManifest writes <dir>/manifest.json with schema, qt
(version, debug, pictureFormat, sidecar, platform, colorScheme),
surface, sentinels and streams, and returns false with
write-failed: <path>.
A saved row proves only that its files were written and read back
byte-identical. directDifference == 0 proves that the in-memory stream
reproduces the owner's direct render in the recorder's process. Fidelity
across builds is decided by the replay: its digest must equal
referenceSha256, its fonts must resolve like the recorder's, and the
parsed sidecar lists must have the row's counts. The list counts and digests decide completeness:
optimized Qt plays a stream whose sidecar entries are missing as true and
paints it wrong, while only Debug Qt asserts.
LoadPaintStream returns error as one of, in decision order:
invalid-stream-name, missing-stream-file, empty-stream-file,
missing-sidecar, empty-sidecar, picture-format-mismatch,
stream-load-failed, sidecar-unreadable, sidecar-version-mismatch,
sidecar-count-mismatch; identity always carries {bytes, sha256} of the
files it read. The replayer adds playback-failed and missing-pair per
row and its own fatal errors; the assessor's codes and the actions for them
are in the recipe. Every refusal leaves the measurement undecided, never
passed.
Lifetime and cleanup
A PaintRecording owns its picture, whose lists keep shared copies of the
images, pixmaps, brushes and pens the owner painted until the recording is
destroyed. The header keeps no global state, installs nothing and writes only
under the directory the caller passes, so there is nothing to release in
Runner::onFinish.
Verification
python3 .agents/shared/evidence/paint_replay_test.py -v is the self-test.
Its component class builds the standalone component in Release and Debug Qt,
records the synthetic opaque owner with the Debug-Qt fixture under cocoa,
gates and runs the optimized replayer and assesses the result. The owner
draws an image whose rows are padded to 64 bytes, so the positive digests
cover a non-default stride. It catches a deleted, emptied or swapped sidecar,
an emptied, corrupted or header-only stream, a container recorded as the
owner, a translucent child owner recorded with the default flags, a
band-only timed region, a self-paired absent control, a replay without the
font, a changed Qt version or platform and a Debug replayer. It needs macOS,
cmake, the repository font Telegram/lib_ui/fonts/OpenSans-Regular.ttf and
a logged-in GUI session for the cocoa plugin. No Telegram translation unit includes the header; the
component builds compile it with Telegram's QT_NO_KEYWORDS,
QT_NO_CAST_FROM_BYTEARRAY and QT_DEPRECATED_WARNINGS_SINCE definitions and
-Wall -Wextra, so an in-target compile is not verified.
Related guidance
- Paint replay recipe: component build, gate, replay, assessment, refusals and timing limits.
- Motion-window assessment: judging rest, pressed and release windows from the same manifest rows.
- test_animation_clock: clocked input whose
actionStarted/actionFinishedbracket the window's origin actions. - test_probe: handler-time telemetry for exact time origins.