[Docs, Chore] (docs, tools, MobileGL, scripts, CONTRIBUTING.md, .gitignore): translate the documentation and use US spelling

This commit is contained in:
BZLZHH
2026-10-31 19:58:19 +08:00
parent 47892afddc
commit 4f50bedde0
512 changed files with 2955 additions and 2945 deletions
+3 -3
View File
@@ -207,7 +207,7 @@ build-test/tools/trace_replay/mobilegl_trace_replay \
```
At each call boundary it walks every live framebuffer object (or only the named
ones), reads back every colour attachment and the depth attachment, and writes
ones), reads back every color attachment and the depth attachment, and writes
`fbo<N>-att<M>.png` / `fbo<N>-depth.png` plus a `manifest.txt` line per
attachment recording the attached object, size, internal format, component type
and per-channel min/max/mean and a content hash. Attachments are read as floats
@@ -326,7 +326,7 @@ case pass" but "which cases diverge, and is the divergence reproducible":
The archive exists because `.trace-work/android-retrace-result/<case>-<backend>/` is
keyed by case and backend and by nothing else: without `--archive-dir` the only
artefact that survives a three-repeat run is the last one, and "were the three
artifact that survives a three-repeat run is the last one, and "were the three
repeats the same picture?" becomes unanswerable after the fact.
```sh
@@ -539,7 +539,7 @@ its old local 180-second budget. A growing log does not bypass the explicit abso
On timeout the driver terminates and reaps the entire case process group,
including a child that ignores TERM after CMake exits, and stops the matrix to
avoid cascading Busy failures. Check the peer before resuming. Ctrl-C/TERM/HUP
also clean up the group and save a cancelled checkpoint.
also clean up the group and save a canceled checkpoint.
Each attempt has a new directory. `checkpoint.json` is written atomically, and
only a zero exit plus current-attempt successful result, matching backend/call/
+2 -2
View File
@@ -22,7 +22,7 @@
#endif
#include <vector>
// Dumps every colour attachment (and the depth attachment) of every live framebuffer
// Dumps every color attachment (and the depth attachment) of every live framebuffer
// object at a chosen call boundary, on both sides of a driver comparison. The intent is
// to name the first attachment whose contents diverge between two stacks; the manifest is
// formatted so that `diff` over two dump directories points straight at it.
@@ -350,7 +350,7 @@ namespace mobilegl_trace_dump {
return DrainErrors() == 0;
}
// Reads the attachment as floats regardless of its storage: normalised and float targets
// Reads the attachment as floats regardless of its storage: normalized and float targets
// convert on the way out, integer targets are read as integers and widened. The float view
// keeps out-of-[0,1] accumulation buffers legible in the statistics even though the PNG
// itself has to clamp.
+7 -7
View File
@@ -11,7 +11,7 @@
WHY THIS EXISTS. `result.json` carries ONE number per run: this attempt's actual against its
golden. P7-7 E0 asks a different question - "are three repeats of the same case on the same
device the same picture?" - and no artefact in the tree answers it, because every repeat
device the same picture?" - and no artifact in the tree answers it, because every repeat
overwrites the previous one's `.trace-work/android-retrace-result/<case>-<backend>/`. With the
repeats archived (`run_android_retrace_local.py --archive-dir`), this script computes the
missing pair: SSIM(repeat N, repeat 1) beside the recorded SSIM(repeat N, golden).
@@ -19,7 +19,7 @@ missing pair: SSIM(repeat N, repeat 1) beside the recorded SSIM(repeat N, golden
THE SSIM IS NOT A NEW ONE. It is a transcription of the retrace gate's own comparator,
`android-plugin/app/src/trace/cpp/trace_replay_core.cpp:630` (`ComputeChannelSsim`) and `:671`
(`ComputeRgbSsim`) - a single global window per channel, C1 = (0.01*255)^2, C2 = (0.03*255)^2,
the three colour channels averaged and alpha ignored - and the crop comes from the repeat's own
the three color channels averaged and alpha ignored - and the crop comes from the repeat's own
`result.json`, so the window is the one the gate scored. A different SSIM (a gaussian-windowed
one, say) would produce numbers that could not be read beside the recorded ones at all, which is
the whole reason this file does not import a library implementation.
@@ -56,7 +56,7 @@ class ImageError(ValueError):
# PNG decode. Deliberately stdlib-only (zlib): this script has to run in the device window on
# whatever interpreter is at hand, and an unavailable Pillow would turn "the repeats diverged"
# into "the tool did not run", which are not the same finding. The accepted subset is what
# libpng gives trace_replay_core after its own normalisation (ReadPngRgba, :278): 8- and 16-bit
# libpng gives trace_replay_core after its own normalization (ReadPngRgba, :278): 8- and 16-bit
# greyscale/RGB/greyscale+alpha/RGBA and 8-bit palette, non-interlaced. Anything else is
# REFUSED BY NAME rather than guessed at.
# ---------------------------------------------------------------------------------------------
@@ -166,9 +166,9 @@ def read_png_rgba(path):
if interlace != 0:
raise ImageError("interlaced PNG is not supported: " + str(path))
if color_type not in _CHANNELS:
raise ImageError("unsupported PNG colour type %d: %s" % (color_type, path))
raise ImageError("unsupported PNG color type %d: %s" % (color_type, path))
if depth not in (8, 16) or (color_type == 3 and depth != 8):
raise ImageError("unsupported PNG bit depth %d (colour type %d): %s"
raise ImageError("unsupported PNG bit depth %d (color type %d): %s"
% (depth, color_type, path))
channels = _CHANNELS[color_type]
sample_bytes = depth // 8
@@ -241,7 +241,7 @@ def channel_ssim(actual, golden, x0, y0, compare_width, compare_height, channel)
def rgb_ssim(actual, golden, x0, y0, compare_width, compare_height):
"""trace_replay_core.cpp:671 ComputeRgbSsim - the three colour channels, alpha ignored."""
"""trace_replay_core.cpp:671 ComputeRgbSsim - the three color channels, alpha ignored."""
total = 0.0
for channel in range(3):
total += channel_ssim(actual, golden, x0, y0, compare_width, compare_height, channel)
@@ -494,7 +494,7 @@ def self_test():
expect("inverted halves", compare_files(a, b)["ssim"], -0.9964064683569576)
if compare_files(a, b)["mismatch_pixels"] != width * height:
failures.append("inverted halves: every pixel should differ")
# The crop is honoured: the left half of `halves` is black and the left half of
# The crop is honored: the left half of `halves` is black and the left half of
# `inverse` is white, so cropping to it reproduces the black/white number.
cropped = compare_files(a, b, 0, 0, width // 2, height)["ssim"]
expect("cropped half", cropped, 9.999000099990002e-05)
@@ -65,7 +65,7 @@ BACKENDS = {
# canonical id - signed by whichever key was current when it was made - otherwise has to have that
# install destroyed before an A/B can run, which is destructive and, on a shared bench, rude.
#
# ABSENT MEANS THE CANONICAL ID, so every existing caller keeps the behaviour it had. What the
# ABSENT MEANS THE CANONICAL ID, so every existing caller keeps the behavior it had. What the
# override does NOT change: the Activity class, the intent action, the extras, the on-device app dir
# and the arm-proof markers all stay identical, so the lane under test is the real lane. The one
# thing that must move with it is `--package` in the same command, because trace-replay-ci.sh drives
@@ -292,7 +292,7 @@ def run_case(case, backend, extra_args=None, timeout_seconds=None, env_overrides
# P7-7 repeat archiving.
#
# WHY IT IS NOT OPTIONAL FOR E0. `.trace-work/android-retrace-result/<case>-<backend>/` is keyed
# by case and backend and by nothing else, so repeat 2 overwrites repeat 1 and the only artefact
# by case and backend and by nothing else, so repeat 2 overwrites repeat 1 and the only artifact
# that survives a three-repeat run is the last one. That makes "is this case's divergence
# REPRODUCIBLE, and are the three repeats the same picture?" - the first question P7-7 E0 asks -
# unanswerable after the fact, and the device window is the one place where re-running to find
@@ -446,8 +446,8 @@ def cpu_tail(report):
benchmark.json carries the WHOLE frameCpuTimesMs[] array precisely so that p99 - which the
device does not compute, and which the paired A/B publishes beside p50 - is a host-side
reduction over an artefact that already exists. The window is the same trailing tailFrames the
device summarised, so the numbers below sit beside the device's own without being about a
reduction over an artifact that already exists. The window is the same trailing tailFrames the
device summarized, so the numbers below sit beside the device's own without being about a
different set of frames; p50 is recomputed here by the device's own median rule, so it agrees
with medianFrameCpuMs on the same run rather than merely sitting next to it.
"""
@@ -700,9 +700,9 @@ def main():
return 2
if args.benchmark and args.transport != "monolith":
# REFUSED RATHER THAN RUN UNDER A NAME THAT LIES. run_benchmark_case passes args.env
# alone, so --benchmark --transport spawn has always produced a MONOLITH run labelled
# alone, so --benchmark --transport spawn has always produced a MONOLITH run labeled
# spawn (tools/device_bench/p6/README.md records the same pitfall). The knob the
# benchmark path does honour is --env, so say that instead of silently ignoring this.
# benchmark path does honor is --env, so say that instead of silently ignoring this.
print("--benchmark ignores --transport; pass the arm explicitly, e.g. "
f"--env MOBILEGL_TRANSPORT={args.transport} "
"--env MOBILEGL_IPC_ROLE_SPLIT_STATE=1 --env MOBILEGL_IPC_STRICT_ERRORS=1 "
+1 -1
View File
@@ -532,7 +532,7 @@ def main(argv=None):
# ledgers; otherwise the wrapper sees rc=124 but no
# results.json and cannot distinguish cancellation from a
# driver that never wrote evidence.
row.update(status="cancelled", returncode=130,
row.update(status="canceled", returncode=130,
completed_at_ns=time.time_ns())
row.setdefault("seconds", round((row["completed_at_ns"] - row["started_at_ns"]) / 1e9, 3))
atomic_json(checkpoint_path, checkpoint)
+1 -1
View File
@@ -371,7 +371,7 @@ if(DEFINED ENV{MOBILEGL_TRANSPORT} AND NOT "$ENV{MOBILEGL_TRANSPORT}" STREQUAL "
message(FATAL_ERROR
"MOBILEGL_TRANSPORT=$ENV{MOBILEGL_TRANSPORT} is set for ${split_case} and this "
"runner has no marker for it, so the run could not be checked. ConfigLoader "
"recognises monolith|inproc|spawn|unix:<path>|pipe:<name> and REFUSES the last "
"recognizes monolith|inproc|spawn|unix:<path>|pipe:<name> and REFUSES the last "
"two BY NAME, staying on monolith - a run that asked for one of those would "
"have replayed monolith. Add a row above when the transport lands; do not let "
"an unasserted transport reach a green.")
+2 -2
View File
@@ -272,7 +272,7 @@ class Archive(unittest.TestCase):
self.assertEqual({row["arm"] for row in report["rows"]}, {self.arm})
def test_a_repeat_that_produced_nothing_leaves_an_empty_directory_not_the_previous_one(self):
"""A failed repeat must not inherit the previous repeat's artefacts.
"""A failed repeat must not inherit the previous repeat's artifacts.
This is the concrete shape tools/device_bench/p6/README.md records for benchmark.json:
the result root is not cleared between runs, so a run that produced nothing leaves the
@@ -288,7 +288,7 @@ class Archive(unittest.TestCase):
kept = retrace.archive_repeat(archive, self.case, "DirectVulkan", 2)
self.assertFalse((kept / "result.json").exists())
report = ca.summarize(archive)
# Both artefacts are gone; the first missing one is the one named.
# Both artifacts are gone; the first missing one is the one named.
self.assertEqual(report["rows"][1]["error"], "no result.json")
self.assertNotIn("ssim_vs_first", report["rows"][1])
self.assertNotIn("actual_sha256", report["rows"][1])
+2 -2
View File
@@ -167,13 +167,13 @@ class MatrixTests(unittest.TestCase):
self.assertEqual(self.run_main(), 130)
checkpoint = self.checkpoint()
self.assertEqual(len(checkpoint), 1)
self.assertEqual(checkpoint[0]['status'], 'cancelled')
self.assertEqual(checkpoint[0]['status'], 'canceled')
self.assertEqual(checkpoint[0]['returncode'], 130)
self.assertGreaterEqual(checkpoint[0]['seconds'], 0)
self.assertIn('completed_at_ns', checkpoint[0])
result = matrix.read_json(self.out/'results.json')
self.assertEqual(len(result), 1)
self.assertEqual(result[0]['status'], 'cancelled')
self.assertEqual(result[0]['status'], 'canceled')
self.assertFalse(result[0]['resumed'])
self.assertEqual(self.run_main('--resume'), 0)
self.assertEqual(len(self.checkpoint()), 2)
+1 -1
View File
@@ -47,7 +47,7 @@ namespace {
<< " GPU completion and not just CPU submission (default: 1)\n"
<< " --benchmark-result=PATH Timing JSON output (default: OUTPUT/benchmark.json)\n"
<< " --dump-fbo-attachments CALL:DIR[:FBO,FBO,...]\n"
<< " At CALL, write every colour attachment and the depth\n"
<< " At CALL, write every color attachment and the depth\n"
<< " attachment of every live framebuffer object into DIR as\n"
<< " fbo<N>-att<M>.png / fbo<N>-depth.png, plus a manifest.txt\n"
<< " of formats and per-channel statistics. Repeatable.\n";