F3 shows the shader pack's GPU time per pass, for either kind of pack

While the F3 overlay is open, the running pack's passes are timed on the GPU,
a shaders/ pack's or a native pack's, and the overlay lists the pack's total
and its costliest passes (the median of the last 15 timed frames). The timer
never waits: a timed frame's stamps are resolved once the GPU has finished it
and read back once mapped, then the next frame is timed. A native pack's first
pass counts from a mark that ends with the world's draws, so it does not carry
the time it waited for them. HORIZON_SHADER_PACK_TIMING still logs the medians.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-26 05:59:02 +01:00
parent 5bcc87983e
commit c3763ff1b3
9 changed files with 334 additions and 79 deletions
@@ -84,6 +84,33 @@ impl Displayer {
}
}
/// Horizon's own lines: the shader pack's GPU time, then its costliest passes (`passes`: each
/// pass's median milliseconds, in the order they run).
pub fn shader_pass_lines(passes: &[(String, f32)]) -> Vec<String> {
const SHOWN: usize = 8;
if passes.is_empty() {
return Vec::new();
}
let total: f32 = passes.iter().map(|p| p.1).sum();
let mut lines = vec![format!(
"Shader pack GPU: {total:.2} ms in {} passes",
passes.len()
)];
let mut costliest: Vec<&(String, f32)> = passes.iter().collect();
costliest.sort_by(|a, b| b.1.total_cmp(&a.1));
lines.extend(
costliest
.iter()
.take(SHOWN)
.map(|(name, ms)| format!("{name}: {ms:.2} ms")),
);
if costliest.len() > SHOWN {
let rest: f32 = costliest[SHOWN..].iter().map(|p| p.1).sum();
lines.push(format!("{} more: {rest:.2} ms", costliest.len() - SHOWN));
}
lines
}
/// `Mth.wrapDegrees`.
fn wrap_degrees(angle: f32) -> f32 {
let wrapped = angle % 360.0;
@@ -337,4 +364,15 @@ mod tests {
(1.0, [640, 360])
);
}
#[test]
fn shader_pass_lines_list_the_costliest_passes_first() {
assert!(shader_pass_lines(&[]).is_empty());
let passes: Vec<(String, f32)> = (0..10).map(|i| (format!("p{i}"), i as f32)).collect();
let lines = shader_pass_lines(&passes);
assert_eq!(lines[0], "Shader pack GPU: 45.00 ms in 10 passes");
assert_eq!(lines[1], "p9: 9.00 ms");
assert_eq!(lines[8], "p2: 2.00 ms");
assert_eq!(lines[9], "2 more: 1.00 ms");
}
}
+4 -1
View File
@@ -10495,7 +10495,10 @@ impl Game<'_> {
menu_blur: self.menu_blur(),
};
let result = match self.renderer.as_mut() {
Some(renderer) => horizon_client::spans::time("renderer", || renderer.render(&frame)),
Some(renderer) => {
renderer.set_pass_timing(self.debug);
horizon_client::spans::time("renderer", || renderer.render(&frame))
}
None => Err("renderer".into()),
};
// Restore storage even when rendering fails (for example, a lost surface).
@@ -415,6 +415,13 @@ impl Game<'_> {
],
);
}
// Horizon's own: the shader pack's GPU time per pass (an empty group would move others).
let pass_lines = self.renderer.as_ref().map_or_else(Vec::new, |r| {
debug_overlay::shader_pass_lines(&r.shader_pass_times())
});
if !pass_lines.is_empty() {
d.group("shader pack", pass_lines);
}
// tps: DebugEntryTps for local and remote connections.
if self.player.is_some() {
let [tx, rx] = self.debug_charts.packet_rates.map(|n| n.round() as i64);
+42
View File
@@ -502,6 +502,8 @@ pub struct Renderer {
pack_post: Option<(i32, Option<pack_post::PackPost>)>,
/// The post passes of one of Horizon's own shader packs; never beside `pack_post`'s.
native_post: Option<native_post::NativePost>,
/// Time the shader pack's passes on the GPU (F3, or `HORIZON_SHADER_PACK_TIMING`).
pass_timing: bool,
/// The entity vertices Horizon draws itself while a shader pack draws the others.
pack_entity_rest: Vec<Vertex>,
/// Set 1 of the cloud pipeline, for a shader pack's `gbuffers_clouds`.
@@ -2413,6 +2415,7 @@ impl Renderer {
world_post,
pack_post: None,
native_post: None,
pass_timing: pack_timing::PassTiming::logging(),
pack_entity_rest: Vec::new(),
cloud_bindings,
pack_weather: None,
@@ -2992,6 +2995,34 @@ impl Renderer {
.terrain_inputs(self.pack_terrain_flat),
)
}
/// Times the shader pack's passes on the GPU while `on` (the F3 overlay is open), or always
/// with `HORIZON_SHADER_PACK_TIMING`.
pub fn set_pass_timing(&mut self, on: bool) {
self.pass_timing = on || pack_timing::PassTiming::logging();
}
/// The running shader pack's timer, of either kind.
fn pass_timer<'a>(
pack: &'a mut Option<(i32, Option<pack_post::PackPost>)>,
native: &'a mut Option<native_post::NativePost>,
) -> Option<&'a mut Option<pack_timing::PassTiming>> {
match (pack, native) {
(Some((_, Some(post))), _) => Some(&mut post.timing),
(_, Some(post)) => Some(&mut post.timing),
_ => None,
}
}
/// Each pass of the running shader pack with its median GPU time in milliseconds, while
/// they are timed (`set_pass_timing`).
pub fn shader_pass_times(&self) -> Vec<(String, f32)> {
let timer = match (&self.pack_post, &self.native_post) {
(Some((_, Some(post))), _) => post.timing.as_ref(),
(_, Some(post)) => post.timing.as_ref(),
_ => None,
};
timer
.map(pack_timing::PassTiming::medians)
.unwrap_or_default()
}
/// The dimension the shader pack was last set for.
pub fn shader_pack_dimension(&self) -> Option<i32> {
self.pack_post.as_ref().map(|p| p.0)
@@ -4016,6 +4047,14 @@ impl Renderer {
let pack_post = !frame.title && self.pack_post.as_ref().is_some_and(|p| p.1.is_some());
// One of Horizon's own packs reads the same world target.
let native_post = !frame.title && self.native_post.is_some();
if let Some(timer) = Self::pass_timer(&mut self.pack_post, &mut self.native_post)
&& timer.is_some() != self.pass_timing
{
*timer = self
.pass_timing
.then(|| pack_timing::PassTiming::new(&self.device, &self.queue))
.flatten();
}
let pack_reads_world = pack_post || native_post;
// The pack's program reads the vertices this frame's draws bind.
let pack_draws_terrain = pack_terrain && flat_frame == self.pack_terrain_flat;
@@ -4649,6 +4688,9 @@ impl Renderer {
timer.submitted(&self.queue);
timer.collect(&self.device, &mut self.gpu_times);
}
if let Some(Some(timer)) = Self::pass_timer(&mut self.pack_post, &mut self.native_post) {
timer.submitted(&self.queue);
}
if let Some((path, buffer)) = readback {
self.screenshot_result = Some(
self.write_screenshot(&path, &buffer)
@@ -27,6 +27,10 @@ pub struct NativePost {
groups: Option<(WorldViews, Vec<wgpu::BindGroup>)>,
start: std::time::Instant,
frames: u32,
/// The screen's colour format, the world target's too.
format: wgpu::TextureFormat,
/// GPU time of each pass, while the renderer asks for it (`pack_timing.rs`).
pub timing: Option<super::pack_timing::PassTiming>,
}
fn texture_entry(binding: u32, sample_type: wgpu::TextureSampleType) -> wgpu::BindGroupLayoutEntry {
@@ -165,6 +169,8 @@ impl NativePost {
groups: None,
start: std::time::Instant::now(),
frames: 0,
format,
timing: None,
})
}
@@ -287,6 +293,10 @@ impl NativePost {
) {
self.prepare(device, world, size);
queue.write_buffer(&self.frame, 0, bytemuck::bytes_of(inputs));
if let Some(t) = &mut self.timing {
t.begin(device, queue);
t.mark(device, encoder, (world.0, self.format));
}
let Some((_, groups)) = &self.groups else {
return;
};
@@ -307,6 +317,7 @@ impl NativePost {
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some(label),
color_attachments: &attachments,
timestamp_writes: self.timing.as_mut().and_then(|t| t.writes(label)),
..Default::default()
});
pass.set_pipeline(pipeline);
+3 -3
View File
@@ -297,8 +297,8 @@ pub struct PackPost {
/// with the page buffer it was made for.
block_ids: Option<(wgpu::BindGroupLayout, wgpu::Buffer)>,
page_groups: HashMap<u32, (wgpu::Buffer, wgpu::BindGroup)>,
/// `HORIZON_SHADER_PACK_TIMING`: GPU time of each pass, in the log.
timing: Option<super::pack_timing::PassTiming>,
/// GPU time of each pass, while the renderer asks for it (`pack_timing.rs`).
pub timing: Option<super::pack_timing::PassTiming>,
/// `shaders.properties`' custom uniforms, after the frame's in `uniforms.values`.
custom: horizon_shaders::Custom,
atlas: Option<wgpu::TextureView>,
@@ -1430,7 +1430,7 @@ impl PackPost {
draws,
block_ids,
page_groups: HashMap::new(),
timing: super::pack_timing::PassTiming::new(device, queue),
timing: None,
custom,
atlas: world.atlas.as_ref().map(|a| a.0.clone()),
lightmap: world.lightmap,
+222 -68
View File
@@ -1,31 +1,53 @@
//! Developers' aid: `HORIZON_SHADER_PACK_TIMING=1` times every pass of a shader pack on the
//! GPU, one frame in `EVERY`, and logs each pass's median every `REPORT` timed frames. The
//! frame after a timed one waits for the GPU before reading the timestamps (Metal resolves
//! them without waiting for the passes that write them), so timing slows the game.
//! GPU time of each pass of a shader pack, of either kind: shown in the F3 overlay while it is
//! open, and logged every `REPORT` timed frames with `HORIZON_SHADER_PACK_TIMING=1`. One frame
//! at a time is timed, and the CPU never waits for it: its timestamps are resolved in a later
//! frame, once the GPU has finished it (Metal resolves them without waiting for the passes that
//! write them), then read back when mapped. The next frame after that is timed again.
use std::collections::VecDeque;
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
const EVERY: u32 = 30;
const REPORT: usize = 30;
/// Passes timed per frame at most (two timestamps each).
const CAPACITY: u32 = 64;
/// Timed frames each pass's median is taken over.
const WINDOW: usize = 15;
pub(super) struct PassTiming {
enum Stage {
/// The next frame is timed.
Idle,
/// The frame being recorded is timed.
Recording,
/// Submitted; the flag is set once the GPU has finished it.
Running(Arc<AtomicBool>),
/// Resolved and copied; the flag is set once the copy is mapped.
Reading(Arc<AtomicBool>, u64),
}
pub struct PassTiming {
queries: wgpu::QuerySet,
resolve: wgpu::Buffer,
read: wgpu::Buffer,
period_ns: f32,
frame: u32,
/// The passes timed in the frame being recorded or waiting to be read, in order.
stage: Stage,
/// The passes of the timed frame, in order.
names: Vec<String>,
timed: bool,
samples: Vec<(String, Vec<f32>)>,
/// Each pass's last `WINDOW` times, in milliseconds.
samples: Vec<(String, VecDeque<f32>)>,
/// Log the medians every `REPORT` timed frames.
log: bool,
/// `mark`'s pipeline, for the target format it was made for.
marker: Option<(wgpu::TextureFormat, wgpu::RenderPipeline)>,
reports: usize,
}
impl PassTiming {
/// `None` when the device can't time passes.
pub fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Option<Self> {
if std::env::var_os("HORIZON_SHADER_PACK_TIMING").is_none()
|| !device.features().contains(wgpu::Features::TIMESTAMP_QUERY)
{
if !device.features().contains(wgpu::Features::TIMESTAMP_QUERY) {
return None;
}
let size = u64::from(CAPACITY) * 2 * 8;
@@ -52,51 +74,133 @@ impl PassTiming {
wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
),
period_ns: queue.get_timestamp_period(),
frame: 0,
stage: Stage::Idle,
names: Vec::new(),
timed: false,
samples: Vec::new(),
log: Self::logging(),
marker: None,
reports: 0,
})
}
/// At the start of a frame: reads the last timed frame's passes, and decides whether this
/// one is timed.
/// Whether `HORIZON_SHADER_PACK_TIMING` asks for timing without the F3 overlay.
pub fn logging() -> bool {
static LOG: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
*LOG.get_or_init(|| std::env::var_os("HORIZON_SHADER_PACK_TIMING").is_some())
}
/// At the start of a frame's passes: moves the last timed frame along, and decides whether
/// this one is timed.
pub fn begin(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
if self.timed && !self.names.is_empty() {
self.collect(device, queue);
match &self.stage {
// A timed frame that was never submitted: time this one instead.
Stage::Recording => self.stage = Stage::Idle,
Stage::Running(done) if done.load(Ordering::Acquire) => {
let bytes = self.names.len() as u64 * 16;
let mut encoder = device.create_command_encoder(&Default::default());
encoder.resolve_query_set(
&self.queries,
0..self.names.len() as u32 * 2,
&self.resolve,
0,
);
encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.read, 0, bytes);
queue.submit([encoder.finish()]);
let mapped = Arc::new(AtomicBool::new(false));
let flag = mapped.clone();
self.read
.slice(..bytes)
.map_async(wgpu::MapMode::Read, move |r| {
flag.store(r.is_ok(), Ordering::Release)
});
self.stage = Stage::Reading(mapped, bytes);
}
Stage::Reading(mapped, bytes) if mapped.load(Ordering::Acquire) => {
let bytes = *bytes;
self.collect(bytes);
self.stage = Stage::Idle;
}
_ => {}
}
if matches!(self.stage, Stage::Idle) {
self.names.clear();
self.stage = Stage::Recording;
}
self.names.clear();
self.frame += 1;
self.timed = self.frame.is_multiple_of(EVERY);
}
/// Timestamp writes for the pass `name`, in a timed frame.
pub fn writes(&mut self, name: &str) -> Option<wgpu::RenderPassTimestampWrites<'_>> {
let i = self.push(name)?;
Some(stamps(&self.queries, i))
}
/// The index of the timed frame's next pass, `name`.
fn push(&mut self, name: &str) -> Option<u32> {
let i = self.names.len() as u32;
if !self.timed || i >= CAPACITY {
if !matches!(self.stage, Stage::Recording) || i >= CAPACITY {
return None;
}
self.names.push(name.to_owned());
Some(wgpu::RenderPassTimestampWrites {
query_set: &self.queries,
beginning_of_pass_write_index: Some(2 * i),
end_of_pass_write_index: Some(2 * i + 1),
})
Some(i)
}
fn collect(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
// The timed frame first, then the resolve, so every timestamp is written.
_ = device.poll(wgpu::PollType::wait_indefinitely());
let count = self.names.len() as u32 * 2;
let bytes = u64::from(count) * 8;
let mut encoder = device.create_command_encoder(&Default::default());
encoder.resolve_query_set(&self.queries, 0..count, &self.resolve, 0);
encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.read, 0, bytes);
queue.submit([encoder.finish()]);
/// A pass that ends once everything drawn into `target` before it has, in a timed frame:
/// the next pass counts from there, not from when the GPU queued it behind them.
pub fn mark(
&mut self,
device: &wgpu::Device,
encoder: &mut wgpu::CommandEncoder,
(target, format): super::timing::Target,
) {
if self.marker.as_ref().is_none_or(|(f, _)| *f != format) {
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("Shader pack timing mark"),
source: wgpu::ShaderSource::Wgsl(super::timing::MARKER.into()),
});
let pipeline = super::timing::end_pipeline(device, &module, format);
self.marker = Some((format, pipeline));
}
// An unnamed pass: its end counts, it is never listed.
let Some(i) = self.push("") else {
return;
};
let (_, pipeline) = self.marker.as_ref().expect("made above");
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some("Shader pack timing mark"),
color_attachments: &[Some(wgpu::RenderPassColorAttachment {
view: target,
depth_slice: None,
resolve_target: None,
ops: wgpu::Operations {
load: wgpu::LoadOp::Load,
store: wgpu::StoreOp::Store,
},
})],
timestamp_writes: Some(stamps(&self.queries, i)),
..Default::default()
});
pass.set_pipeline(pipeline);
pass.set_scissor_rect(0, 0, 1, 1);
pass.draw(0..3, 0..1);
}
/// After the frame is submitted.
pub fn submitted(&mut self, queue: &wgpu::Queue) {
if !matches!(self.stage, Stage::Recording) {
return;
}
if self.names.is_empty() {
self.stage = Stage::Idle;
return;
}
let done = Arc::new(AtomicBool::new(false));
let flag = done.clone();
queue.on_submitted_work_done(move || flag.store(true, Ordering::Release));
self.stage = Stage::Running(done);
}
fn collect(&mut self, bytes: u64) {
let slice = self.read.slice(..bytes);
slice.map_async(wgpu::MapMode::Read, |_| {});
_ = device.poll(wgpu::PollType::wait_indefinitely());
let Ok(data) = slice.get_mapped_range() else {
return;
};
@@ -108,41 +212,91 @@ impl PassTiming {
.collect();
drop(data);
self.read.unmap();
// Passes overlap on tiled GPUs (a pass begins before the one before it ends): a pass
// costs the time from the later of its beginning and the previous pass's end.
let mut previous_end = 0;
for (name, pair) in self.names.iter().zip(stamps.as_chunks::<2>().0) {
if pair[0] == 0 || pair[1] < pair[0] {
let times = pass_times(&stamps, self.period_ns);
for (name, ms) in self.names.iter().zip(times) {
let Some(ms) = ms.filter(|_| !name.is_empty()) else {
continue;
};
let i = match self.samples.iter().position(|s| s.0 == *name) {
Some(i) => i,
None => {
self.samples.push((name.clone(), VecDeque::new()));
self.samples.len() - 1
}
};
let window = &mut self.samples[i].1;
if window.len() == WINDOW {
window.pop_front();
}
let from = pair[0].max(previous_end).min(pair[1]);
previous_end = pair[1];
let ms = (pair[1] - from) as f32 * self.period_ns / 1e6;
match self.samples.iter_mut().find(|s| s.0 == *name) {
Some(s) => s.1.push(ms),
None => self.samples.push((name.clone(), vec![ms])),
}
window.push_back(ms);
}
self.reports += 1;
if self.reports.is_multiple_of(REPORT) {
self.report();
if self.log && self.reports.is_multiple_of(REPORT) {
let medians = self.medians();
let total: f32 = medians.iter().map(|m| m.1).sum();
let parts: Vec<String> = medians
.iter()
.map(|(n, ms)| format!("{n} {ms:.3}"))
.collect();
log::info!(
"shader pack GPU time per pass (median ms of the last {WINDOW} timed frames): {} = {total:.3}",
parts.join(", ")
);
}
}
fn report(&mut self) {
let mut total = 0.0;
let mut parts = Vec::new();
// A pass that did not run in this window (no entities, the sky out of sight) is left out.
for (name, v) in self.samples.iter_mut().filter(|s| !s.1.is_empty()) {
v.sort_by(f32::total_cmp);
let median = v[v.len() / 2];
total += median;
parts.push(format!("{name} {median:.3}"));
v.clear();
}
log::info!(
"shader pack GPU time per pass (median ms of {REPORT} frames): {} = {total:.3}",
parts.join(", ")
);
/// Each pass's median time in milliseconds over its last timed frames, in the order the
/// passes first ran.
pub fn medians(&self) -> Vec<(String, f32)> {
self.samples
.iter()
.filter(|s| !s.1.is_empty())
.map(|(name, v)| {
let mut v: Vec<f32> = v.iter().copied().collect();
v.sort_by(f32::total_cmp);
(name.clone(), v[v.len() / 2])
})
.collect()
}
}
/// Pass `i`'s beginning and end timestamps.
fn stamps(queries: &wgpu::QuerySet, i: u32) -> wgpu::RenderPassTimestampWrites<'_> {
wgpu::RenderPassTimestampWrites {
query_set: queries,
beginning_of_pass_write_index: Some(2 * i),
end_of_pass_write_index: Some(2 * i + 1),
}
}
/// Each pass's time in milliseconds from its (beginning, end) timestamps, `None` for a pass
/// the GPU left unstamped. Passes overlap on tiled GPUs (a pass begins before the one before it
/// ends): a pass costs the time from the later of its beginning and the previous pass's end.
fn pass_times(stamps: &[u64], period_ns: f32) -> Vec<Option<f32>> {
let mut previous_end = 0;
stamps
.as_chunks::<2>()
.0
.iter()
.map(|&[begin, end]| {
if begin == 0 || end < begin {
return None;
}
let from = begin.max(previous_end).min(end);
previous_end = end;
Some((end - from) as f32 * period_ns / 1e6)
})
.collect()
}
#[cfg(test)]
mod tests {
use super::pass_times;
#[test]
fn overlapping_passes_cost_from_the_previous_end() {
// Pass 2 begins before pass 1 ends; pass 3 was never stamped.
let stamps = [1_000_000, 3_000_000, 2_000_000, 5_000_000, 0, 0];
assert_eq!(pass_times(&stamps, 1.0), [Some(2.0), Some(2.0), None]);
}
}
+2 -2
View File
@@ -60,7 +60,7 @@ struct Markers {
/// The start's one thread; the end's triangle over the whole target (the
/// pass's scissor keeps one pixel), shading nothing it writes.
const MARKER: &str =
pub(super) const MARKER: &str =
"@vertex fn cover(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
return vec4<f32>(f32(i & 1u) * 4.0 - 1.0, f32(i >> 1u) * 4.0 - 1.0, 0.0, 1.0);
}
@@ -254,7 +254,7 @@ impl GpuTimer {
}
/// The end marker's pipeline for a `format` target, every write masked.
fn end_pipeline(
pub(super) fn end_pipeline(
device: &wgpu::Device,
module: &wgpu::ShaderModule,
format: wgpu::TextureFormat,
+5 -5
View File
@@ -127,11 +127,11 @@ one keeps drawing), the launcher before it installs one, and the registry's CI b
6. Every entry point translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL), with the options at their
defaults, minimums and maximums.
`[budget] gpu_ms` is the GPU time your pack aims to add to a frame; the game's overlay will show each pass's time
against it.
`[budget] gpu_ms` is the GPU time your pack aims to add to a frame. To compare, open F3 in the game: while it is
open, each pass is timed on the GPU and the overlay shows the pack's total and its costliest passes, by their `name`
(the median of the last 15 timed frames). Timing waits for nothing, so it does not slow the game.
## Next
The renderer hooks (shared with the Iris/OptiFine loader), then the post stage in the game with hot reload and the
GPU time per pass, Options > Shader packs listing these packs, then the material and sky stages, and the registry's
`shader` kind with installs from the launcher.
Options > Shader packs listing these packs, then the material and sky stages, and the registry's `shader` kind with
installs from the launcher.