F7: Offscreen render capture harness
tools/capture.sh <scene-or-scenario> <out.png> renders the real client in a throwaway tidewall-capture-* Docker container (debian:13, Xvfb, Mesa software rendering), with no network, no host display, GPU or audio, and removes the container afterwards. The tidewall-capture image rebuilds only when its recipe changes. Forward+ through Lavapipe is the default, matching the game; CAPTURE_RENDERER=compatibility uses OpenGL through llvmpipe. The script fails if Godot silently falls back to another renderer, and fails on a blank frame, judged by ImageStats (luminance variance and colour count). make capture-test renders the shore test scene with both renderers and proves an empty scene is rejected. ImageStats has unit tests in make check. CLAUDE.md now requires a capture for visual issues, and requires that it be opened and looked at. Closes #7 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
## Renders a scene for a number of frames and saves the last one as a PNG.
|
||||
## Runs inside the tidewall-capture container via tools/capture.sh, never on the host
|
||||
## display. Prints one JSON line with the image statistics and exits:
|
||||
## 0 saved and not blank, 1 blank or failed, 2 bad arguments.
|
||||
##
|
||||
## --scene=res://...tscn --out=res://captures/x.png [--frames=N] [--allow-blank]
|
||||
extends SceneTree
|
||||
|
||||
var _scene: String = ""
|
||||
var _out: String = ""
|
||||
var _frames: int = 30
|
||||
var _allow_blank: bool = false
|
||||
|
||||
|
||||
func _initialize() -> void:
|
||||
for arg: String in OS.get_cmdline_user_args():
|
||||
if arg.begins_with("--scene="):
|
||||
_scene = arg.trim_prefix("--scene=")
|
||||
elif arg.begins_with("--out="):
|
||||
_out = arg.trim_prefix("--out=")
|
||||
elif arg.begins_with("--frames=") and arg.trim_prefix("--frames=").is_valid_int():
|
||||
_frames = maxi(arg.trim_prefix("--frames=").to_int(), 1)
|
||||
elif arg == "--allow-blank":
|
||||
_allow_blank = true
|
||||
else:
|
||||
printerr("capture: unknown argument '%s'" % arg)
|
||||
quit(2)
|
||||
return
|
||||
if _scene.is_empty() or _out.is_empty():
|
||||
printerr("capture: --scene and --out are required")
|
||||
quit(2)
|
||||
return
|
||||
if DisplayServer.get_name() == "headless":
|
||||
printerr("capture: no display; run this through tools/capture.sh")
|
||||
quit(2)
|
||||
return
|
||||
_capture.call_deferred()
|
||||
|
||||
|
||||
func _capture() -> void:
|
||||
var packed: PackedScene = load(_scene) as PackedScene
|
||||
if packed == null:
|
||||
printerr("capture: can't load scene '%s'" % _scene)
|
||||
quit(1)
|
||||
return
|
||||
root.add_child(packed.instantiate())
|
||||
for _index: int in _frames:
|
||||
await process_frame
|
||||
await RenderingServer.frame_post_draw
|
||||
var image: Image = root.get_texture().get_image()
|
||||
var stats: Dictionary = ImageStats.measure(image)
|
||||
var blank: bool = ImageStats.is_blank(stats)
|
||||
var error: Error = image.save_png(_out)
|
||||
stats["scene"] = _scene
|
||||
stats["size"] = [image.get_width(), image.get_height()]
|
||||
stats["renderer"] = RenderingServer.get_current_rendering_method()
|
||||
stats["adapter"] = RenderingServer.get_video_adapter_name()
|
||||
stats["blank"] = blank
|
||||
stats["saved"] = error == OK
|
||||
print("CAPTURE " + JSON.stringify(stats))
|
||||
quit(0 if error == OK and (not blank or _allow_blank) else 1)
|
||||
@@ -0,0 +1 @@
|
||||
uid://00d2aqely5kg
|
||||
Executable
+117
@@ -0,0 +1,117 @@
|
||||
#!/usr/bin/env bash
|
||||
# Renders the real client offscreen and saves a PNG, without touching the host display,
|
||||
# GPU or audio. Godot runs in a throwaway Docker container with a private Xvfb and Mesa
|
||||
# software rendering.
|
||||
#
|
||||
# tools/capture.sh <scene-or-scenario> <out.png> [--frames=N] [--allow-blank]
|
||||
#
|
||||
# <scene-or-scenario> is a res:// path to a .tscn, or the name of a scenario in
|
||||
# test/capture/ (for example `smoke` means res://test/capture/smoke.tscn).
|
||||
#
|
||||
# Environment:
|
||||
# CAPTURE_SIZE=1280x720 frame size
|
||||
# CAPTURE_RENDERER=forward_plus Vulkan via Lavapipe (default, the shipping renderer), or
|
||||
# compatibility for OpenGL via llvmpipe
|
||||
#
|
||||
# Exits 0 when the PNG was written and isn't blank (pixel variance and colour count),
|
||||
# 1 when the render failed or came out blank, 2 on bad usage. Open the image and look
|
||||
# at it anyway: these checks only catch the obvious failures.
|
||||
set -euo pipefail
|
||||
|
||||
repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
image="tidewall-capture"
|
||||
context="$repo/tools/capture"
|
||||
|
||||
usage() {
|
||||
sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
[[ $# -ge 2 ]] || usage
|
||||
target="$1"
|
||||
out="$2"
|
||||
shift 2
|
||||
extra=()
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--frames=* | --allow-blank) extra+=("$arg") ;;
|
||||
*) echo "capture.sh: unknown option '$arg'" >&2; usage ;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [[ "$target" == res://* ]]; then
|
||||
scene="$target"
|
||||
else
|
||||
[[ "$target" =~ ^[a-z0-9_]+$ ]] || { echo "capture.sh: bad scenario name '$target'" >&2; exit 2; }
|
||||
scene="res://test/capture/$target.tscn"
|
||||
fi
|
||||
[[ -f "$repo/${scene#res://}" ]] || { echo "capture.sh: no such scene: $scene" >&2; exit 2; }
|
||||
|
||||
size="${CAPTURE_SIZE:-1280x720}"
|
||||
[[ "$size" =~ ^[0-9]+x[0-9]+$ ]] || { echo "capture.sh: bad CAPTURE_SIZE '$size'" >&2; exit 2; }
|
||||
case "${CAPTURE_RENDERER:-forward_plus}" in
|
||||
compatibility) render=(--rendering-method gl_compatibility --rendering-driver opengl3) ;;
|
||||
forward_plus) render=(--rendering-method forward_plus --rendering-driver vulkan) ;;
|
||||
*) echo "capture.sh: CAPTURE_RENDERER must be compatibility or forward_plus" >&2; exit 2 ;;
|
||||
esac
|
||||
|
||||
# Rebuild the image only when its recipe changes.
|
||||
recipe_hash="$(cat "$context/Dockerfile" "$context/entrypoint.sh" | sha256sum | cut -c1-16)"
|
||||
current="$(docker image inspect "$image" --format '{{ index .Config.Labels "tidewall.recipe" }}' 2>/dev/null || true)"
|
||||
if [[ "$current" != "$recipe_hash" ]]; then
|
||||
echo "capture.sh: building $image" >&2
|
||||
docker build --quiet --label "tidewall.recipe=$recipe_hash" -t "$image" "$context" >/dev/null
|
||||
fi
|
||||
|
||||
# Refresh the global class cache headless on the host, so class_name lookups resolve.
|
||||
"$repo/tools/godot.sh" --import --quit >/dev/null 2>&1 || true
|
||||
|
||||
# The container can only write inside the repo, so render to a scratch file there.
|
||||
mkdir -p "$repo/captures"
|
||||
# Keep Godot from importing captures as project resources.
|
||||
touch "$repo/captures/.gdignore"
|
||||
scratch="captures/.capture-$$-$RANDOM.png"
|
||||
name="tidewall-capture-$$-$RANDOM"
|
||||
cleanup() {
|
||||
docker rm -f "$name" >/dev/null 2>&1 || true
|
||||
rm -f "$repo/$scratch"
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
set +e
|
||||
output="$(timeout --signal=KILL 300 nice -n 15 docker run --rm --name "$name" \
|
||||
--network none \
|
||||
--user "$(id -u):$(id -g)" \
|
||||
--memory 3g --cpus 4 \
|
||||
-e "CAPTURE_SCREEN=${size}x24" \
|
||||
-v "$repo:/repo" \
|
||||
"$image" \
|
||||
"${render[@]}" --resolution "$size" \
|
||||
--script res://tools/capture.gd -- --scene="$scene" --out="res://$scratch" "${extra[@]}" 2>&1)"
|
||||
code=$?
|
||||
set -e
|
||||
|
||||
report="$(grep -m1 '^CAPTURE ' <<<"$output" | cut -c9- || true)"
|
||||
if [[ -z "$report" ]]; then
|
||||
echo "capture.sh: render failed (exit $code)" >&2
|
||||
tail -n 30 <<<"$output" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ -f "$repo/$scratch" ]]; then
|
||||
mkdir -p "$(dirname "$out")"
|
||||
mv "$repo/$scratch" "$out"
|
||||
fi
|
||||
echo "$report"
|
||||
# Godot silently falls back to OpenGL when Vulkan fails; that is not the requested capture.
|
||||
wanted="${render[1]}"
|
||||
if ! grep -q "\"renderer\":\"$wanted\"" <<<"$report"; then
|
||||
echo "capture.sh: asked for the $wanted renderer, but Godot fell back to another" >&2
|
||||
grep -iE 'vulkan|error' <<<"$output" | tail -n 10 >&2 || true
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$code" -ne 0 ]]; then
|
||||
echo "capture.sh: capture of $scene failed or came out blank (exit $code)" >&2
|
||||
grep -iE 'error|fail' <<<"$output" | grep -v '^CAPTURE ' | tail -n 15 >&2 || true
|
||||
exit 1
|
||||
fi
|
||||
echo "capture.sh: wrote $out" >&2
|
||||
@@ -0,0 +1,23 @@
|
||||
# Offscreen render harness for tools/capture.sh: a private X server (Xvfb) and Mesa's
|
||||
# software rasterizers, so Godot can render the real client without any host display,
|
||||
# GPU or audio device. Built as image tidewall-capture.
|
||||
FROM debian:13
|
||||
|
||||
RUN apt-get update \
|
||||
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
|
||||
xvfb xauth \
|
||||
libgl1 libgl1-mesa-dri libglx-mesa0 libegl1 libgles2 \
|
||||
mesa-vulkan-drivers libvulkan1 \
|
||||
libx11-6 libxcursor1 libxinerama1 libxrandr2 libxi6 libxext6 libxrender1 \
|
||||
libxkbcommon0 libxkbcommon-x11-0 \
|
||||
libfontconfig1 libdbus-1-3 libasound2t64 libpulse0 libudev1 \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Never touch a real GPU, even if a device were passed in by mistake.
|
||||
ENV LIBGL_ALWAYS_SOFTWARE=1 \
|
||||
GALLIUM_DRIVER=llvmpipe \
|
||||
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.json \
|
||||
HOME=/tmp/home
|
||||
|
||||
COPY entrypoint.sh /usr/local/bin/tidewall-capture
|
||||
ENTRYPOINT ["/usr/local/bin/tidewall-capture"]
|
||||
Executable
+25
@@ -0,0 +1,25 @@
|
||||
#!/usr/bin/env bash
|
||||
# Runs inside the tidewall-capture container. Starts a private Xvfb, then runs the
|
||||
# repo's pinned Godot against it. Arguments go to Godot after the repo's own flags.
|
||||
set -euo pipefail
|
||||
|
||||
mkdir -p "$HOME"
|
||||
export DISPLAY=:77
|
||||
Xvfb "$DISPLAY" -screen 0 "${CAPTURE_SCREEN:-1280x720x24}" -nolisten tcp -noreset \
|
||||
>/tmp/xvfb.log 2>&1 &
|
||||
xvfb_pid=$!
|
||||
trap 'kill "$xvfb_pid" 2>/dev/null || true' EXIT
|
||||
|
||||
for _ in $(seq 1 50); do
|
||||
[[ -e /tmp/.X11-unix/X77 ]] && break
|
||||
sleep 0.1
|
||||
done
|
||||
if [[ ! -e /tmp/.X11-unix/X77 ]]; then
|
||||
echo "tidewall-capture: Xvfb did not start" >&2
|
||||
cat /tmp/xvfb.log >&2
|
||||
exit 3
|
||||
fi
|
||||
|
||||
# This container's X server is private, so a window here is allowed.
|
||||
export TIDEWALL_GODOT_DISPLAY=1
|
||||
/repo/tools/godot.sh --display-driver x11 --audio-driver Dummy "$@"
|
||||
Executable
+36
@@ -0,0 +1,36 @@
|
||||
#!/usr/bin/env bash
|
||||
# Proves the capture harness works and catches blank renders. Needs Docker; not part of
|
||||
# `make check`, because it builds an image and renders in software. Run: make capture-test
|
||||
set -uo pipefail
|
||||
cd "$(dirname "${BASH_SOURCE[0]}")/.."
|
||||
|
||||
status=0
|
||||
dir="captures/selfcheck"
|
||||
mkdir -p "$dir"
|
||||
|
||||
# expect <exit> <renderer> <scenario>
|
||||
expect() {
|
||||
local wanted="$1" renderer="$2" scenario="$3" code
|
||||
CAPTURE_RENDERER="$renderer" tools/capture.sh "$scenario" "$dir/$scenario-$renderer.png" \
|
||||
>"$dir/$scenario-$renderer.log" 2>&1
|
||||
code=$?
|
||||
if [[ "$code" -ne "$wanted" ]]; then
|
||||
echo "capture-test FAIL $scenario ($renderer): exit $code, expected $wanted"
|
||||
tail -n 15 "$dir/$scenario-$renderer.log"
|
||||
status=1
|
||||
else
|
||||
echo "capture-test ok $scenario ($renderer): exit $code, $(head -n 1 "$dir/$scenario-$renderer.log" | grep -oE '"variance":[0-9.e-]+')"
|
||||
fi
|
||||
}
|
||||
|
||||
expect 0 forward_plus smoke
|
||||
expect 0 compatibility smoke
|
||||
expect 1 forward_plus blank
|
||||
|
||||
leftover="$(docker ps -a --filter name=tidewall-capture- --format '{{.Names}}')"
|
||||
if [[ -n "$leftover" ]]; then
|
||||
echo "capture-test FAIL: containers left behind: $leftover"
|
||||
status=1
|
||||
fi
|
||||
[[ "$status" -eq 0 ]] && echo "capture-test: ok. Now open $dir/smoke-forward_plus.png and look at it."
|
||||
exit "$status"
|
||||
@@ -0,0 +1,45 @@
|
||||
## Measures a captured image, so a blank or broken render fails automatically.
|
||||
## A capture still has to be looked at by a person or agent; this only catches the
|
||||
## obvious failures.
|
||||
class_name ImageStats
|
||||
extends RefCounted
|
||||
|
||||
## Below this luminance variance (on a 0..1 scale) an image counts as blank.
|
||||
const BLANK_VARIANCE: float = 0.0005
|
||||
## A real scene has far more distinct colours than a cleared or broken frame.
|
||||
const BLANK_MAX_COLOURS: int = 16
|
||||
## Sampling stride, in pixels. Enough for a 1280x720 frame in milliseconds.
|
||||
const STRIDE: int = 4
|
||||
|
||||
|
||||
## Returns mean and variance of luminance, and the number of distinct sampled colours.
|
||||
static func measure(image: Image) -> Dictionary:
|
||||
var source: Image = image
|
||||
if source.is_compressed():
|
||||
source = image.duplicate() as Image
|
||||
source.decompress()
|
||||
var sum: float = 0.0
|
||||
var sum_squares: float = 0.0
|
||||
var samples: int = 0
|
||||
var colours: Dictionary = {}
|
||||
for y: int in range(0, source.get_height(), STRIDE):
|
||||
for x: int in range(0, source.get_width(), STRIDE):
|
||||
var colour: Color = source.get_pixel(x, y)
|
||||
var luminance: float = colour.get_luminance()
|
||||
sum += luminance
|
||||
sum_squares += luminance * luminance
|
||||
samples += 1
|
||||
colours[colour.to_rgba32()] = true
|
||||
if samples == 0:
|
||||
return {"samples": 0, "mean": 0.0, "variance": 0.0, "colours": 0}
|
||||
var mean: float = sum / samples
|
||||
return {
|
||||
"samples": samples,
|
||||
"mean": mean,
|
||||
"variance": maxf(sum_squares / samples - mean * mean, 0.0),
|
||||
"colours": colours.size(),
|
||||
}
|
||||
|
||||
|
||||
static func is_blank(stats: Dictionary) -> bool:
|
||||
return stats["variance"] < BLANK_VARIANCE or stats["colours"] <= BLANK_MAX_COLOURS
|
||||
@@ -0,0 +1 @@
|
||||
uid://dwf5l8spiiso2
|
||||
Reference in New Issue
Block a user