summaryrefslogtreecommitdiff
path: root/src/scope/root.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:14:09 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commite997fc3e6b312b30f5af90012fc22365bab701d4 (patch)
tree96c7fee23b50e6b303fd1cf641be5761e98ca09a /src/scope/root.zig
parentc68a8c9d9efa746e8eaef0392a327888577a05e0 (diff)
downloadsketchbook-e997fc3e6b312b30f5af90012fc22365bab701d4.tar.gz
sketchbook-e997fc3e6b312b30f5af90012fc22365bab701d4.zip
scope: its kernels, pipelines and a camera for sketches, and note helpers
A sketch that analyses buffers of its own (micscope's tape of takes) had to copy the scope's shaders to run them. scope.kernels.{waveform, spectrogram, spectrum} and scope.pipelines.{wave, spectrogram, spectrum} are now public, documented with what each reads and writes, beside the parameter and view blocks already in scope.layouts; Scope.gpu.tape is documented as the history on the GPU for a kernel of the sketch's. Views.camera, when given, makes the rects world rects: the views are made at their size there and drawn at camera.toScreen(rect), so moving or zooming the camera recomputes nothing (micscope's world of panels). scope.midi(freq, a4), scope.hz(note, a4) and scope.note_names, as micscope's tuner and spheres' chords each spell them; place() names its argument freq so hz can be the function. Test: notes and frequencies convert both ways (A4 at 440 and 442, E2, middle C, a round trip at 432) and name their pitch class. The README's scope paragraph says all of it. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'src/scope/root.zig')
-rw-r--r--src/scope/root.zig91
1 files changed, 69 insertions, 22 deletions
diff --git a/src/scope/root.zig b/src/scope/root.zig
index a71fa53..098e2d0 100644
--- a/src/scope/root.zig
+++ b/src/scope/root.zig
@@ -16,6 +16,10 @@
//! Columns of the scrolling views are analysed once, when everything their
//! windows reach has arrived, into rings the views read from the oldest; so
//! the spectrogram runs `reach` samples (about 130 ms) behind the newest.
+//!
+//! A sketch that analyses buffers of its own (a tape of takes, say) uses the
+//! same shaders through `kernels` and `pipelines`, with the parameter and
+//! view blocks in `layouts`; `midi`, `hz` and `note_names` name pitches.
const std = @import("std");
const sk = @import("sketch");
const gpu = sk.abi.gpu;
@@ -43,6 +47,10 @@ pub const Views = struct {
oscilloscope: ?Oscilloscope = null,
gain: f32 = 1,
tint: Tint = .live,
+ /// When given, the rects are in its world: the views are made at their
+ /// size there and drawn at `camera.toScreen(rect)`, so moving or zooming
+ /// the camera recomputes nothing.
+ camera: ?sk.Camera = null,
pub const Oscilloscope = struct {
rect: sk.Rect,
@@ -66,6 +74,8 @@ pub const Scope = struct {
filled: u32 = 0,
columns: u32 = 0,
spp: u32 = 0,
+ /// `gpu.tape` holds `samples` on the GPU, as of the last `draw` (a
+ /// `history`-sample buffer, oldest first), for kernels of a sketch's own.
gpu: Gpu = .{},
pub fn push(s: *Scope, heard: []const f32) void {
@@ -91,7 +101,7 @@ pub const Scope = struct {
defer s.fresh = false;
if (v.wave orelse v.spectrogram) |r| s.scroll(f, v, r, rate);
- if (v.spectrum) |r| s.spectrum(f, r, rate);
+ if (v.spectrum) |r| s.spectrum(f, v, r, rate);
if (v.oscilloscope) |o| s.oscilloscope(f, v, o);
}
@@ -121,7 +131,7 @@ pub const Scope = struct {
const slot: u32 = @intCast(s.next % columns);
if (v.wave != null) f.compute(.{
.label = "scope waveform.comp",
- .kernel = waveform_kernel,
+ .kernel = kernels.waveform,
.readonly = &.{g.tape},
.readwrite = &.{g.wave.columns},
.uniforms = gpu.uniform(f.scratch, layouts.WaveParams{ .offset = 0, .first = first, .samples = history, .columns = count, .spp = @floatFromInt(spp), .slot = slot, .ring = columns }),
@@ -129,7 +139,7 @@ pub const Scope = struct {
});
if (v.spectrogram != null) f.compute(.{
.label = "scope spectrogram.comp",
- .kernel = spectrogram_kernel,
+ .kernel = kernels.spectrogram,
.readonly = &.{g.tape},
.readwrite = &.{g.levels},
.uniforms = gpu.uniform(f.scratch, layouts.SpectrogramParams{
@@ -163,7 +173,7 @@ pub const Scope = struct {
.filled = s.filled,
};
if (g.wave.redraw(std.hash.Wyhash.hash(0, std.mem.asBytes(&view)))) wavePass(f, &g.wave, size, view);
- f.image(g.wave.image, wr, .{});
+ f.image(g.wave.image, if (v.camera) |c| c.toScreen(wr) else wr, .{});
}
if (v.spectrogram) |sr| {
const size = target(f, &g.spectrogram, sr, rows);
@@ -181,21 +191,21 @@ pub const Scope = struct {
.width = size[0],
.height = size[1],
.clear = null,
- .pipelines = &spectrogram_pipelines,
+ .pipelines = &pipelines.spectrogram,
.draws = &.{.{ .pipeline = 0, .vertex_count = 3, .fragment_uniforms = gpu.uniform(f.scratch, view), .fragment_storage = &.{g.levels} }},
});
- f.image(g.spectrogram.image, sr, .{});
+ f.image(g.spectrogram.image, if (v.camera) |c| c.toScreen(sr) else sr, .{});
}
}
/// The spectrum of the newest samples, smoothed frame to frame.
- fn spectrum(s: *Scope, f: *sk.Frame, r: sk.Rect, rate: f64) void {
+ fn spectrum(s: *Scope, f: *sk.Frame, v: Views, r: sk.Rect, rate: f64) void {
const g = &s.gpu;
const size = target(f, &g.spectrum, r, layouts.max_rows);
const dt: f64 = @min(@as(f64, @floatFromInt(f.in.dt)) / std.time.ns_per_s, 0.1);
f.compute(.{
.label = "scope spectrum.comp",
- .kernel = spectrum_kernel,
+ .kernel = kernels.spectrum,
.readonly = &.{g.tape},
.readwrite = &.{ g.scratch, g.spectrum.columns },
.uniforms = gpu.uniform(f.scratch, layouts.SpectrumParams{
@@ -217,7 +227,7 @@ pub const Scope = struct {
.width = size[0],
.height = size[1],
.clear = null,
- .pipelines = &spectrum_pipelines,
+ .pipelines = &pipelines.spectrum,
.draws = &.{.{
.pipeline = 0,
.vertex_count = 3,
@@ -231,7 +241,7 @@ pub const Scope = struct {
.fragment_storage = &.{g.spectrum.columns},
}},
});
- f.image(g.spectrum.image, r, .{});
+ f.image(g.spectrum.image, if (v.camera) |c| c.toScreen(r) else r, .{});
}
/// The newest `samples` (less `end`), as a line.
@@ -243,7 +253,7 @@ pub const Scope = struct {
const first: u32 = history - n - end;
f.compute(.{
.label = "scope oscilloscope",
- .kernel = waveform_kernel,
+ .kernel = kernels.waveform,
.readonly = &.{g.tape},
.readwrite = &.{g.oscilloscope.columns},
.uniforms = gpu.uniform(f.scratch, layouts.WaveParams{
@@ -265,7 +275,7 @@ pub const Scope = struct {
.scroll = 0,
.filled = size[0],
});
- f.image(g.oscilloscope.image, o.rect, .{});
+ f.image(g.oscilloscope.image, if (v.camera) |c| c.toScreen(o.rect) else o.rect, .{});
}
};
@@ -274,12 +284,26 @@ pub fn maxFreq(rate: f64) f32 {
return @floatCast(@min(20_000, rate / 2));
}
-/// Where `hz` falls across a spectrum view (or up a spectrogram, from its
+/// Where `freq` falls across a spectrum view (or up a spectrogram, from its
/// bottom): 0 to 1, log frequency.
-pub fn place(hz: f64, rate: f64) f32 {
- return @floatCast(@log(hz / min_freq) / @log(maxFreq(rate) / min_freq));
+pub fn place(freq: f64, rate: f64) f32 {
+ return @floatCast(@log(freq / min_freq) / @log(maxFreq(rate) / min_freq));
+}
+
+/// The MIDI note number of `freq` Hz, fractional (69 is A4, at `a4` Hz:
+/// 440 unless the sketch tunes otherwise).
+pub fn midi(freq: f32, a4: f32) f32 {
+ return 69 + 12 * std.math.log2(freq / a4);
}
+/// The frequency of MIDI note `note`, fractional, in Hz.
+pub fn hz(note: f32, a4: f32) f32 {
+ return a4 * std.math.pow(f32, 2, (note - 69) / 12);
+}
+
+/// Pitch classes by `@mod(note, 12)`, C first.
+pub const note_names = [12][]const u8{ "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B" };
+
// ---------------------------------------------------------------------------
// GPU objects.
@@ -358,7 +382,7 @@ fn wavePass(f: *sk.Frame, v: *View, size: [2]u32, view: layouts.WaveView) void {
.width = size[0],
.height = size[1],
.clear = null,
- .pipelines = &wave_pipelines,
+ .pipelines = &pipelines.wave,
.draws = &.{.{ .pipeline = 0, .vertex_count = 3, .fragment_uniforms = gpu.uniform(f.scratch, view), .fragment_storage = &.{v.columns} }},
});
}
@@ -372,13 +396,26 @@ fn viewPipeline(fragment: []const u8) gpu.Pipeline {
.blend = .none,
};
}
-const wave_pipelines = [_]gpu.Pipeline{viewPipeline(shaders.waveform_frag)};
-const spectrum_pipelines = [_]gpu.Pipeline{viewPipeline(shaders.spectrum_frag)};
-const spectrogram_pipelines = [_]gpu.Pipeline{viewPipeline(shaders.spectrogram_frag)};
-const spectrum_kernel: gpu.Kernel = .{ .code = shaders.spectrum_comp, .readonly_buffers = 1, .readwrite_buffers = 2, .uniform_buffers = 1, .threads = .{ 256, 1, 1 } };
-const spectrogram_kernel: gpu.Kernel = .{ .code = shaders.spectrogram_comp, .readonly_buffers = 1, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 256, 1, 1 } };
-const waveform_kernel: gpu.Kernel = .{ .code = shaders.waveform_comp, .readonly_buffers = 1, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 64, 1, 1 } };
+/// The views' passes: one full-screen triangle each (`vertex_count = 3`),
+/// its `layouts.*View` as fragment uniforms and its analysis as fragment
+/// storage (the waveform's or spectrum's columns, the spectrogram's levels).
+pub const pipelines = struct {
+ pub const wave = [_]gpu.Pipeline{viewPipeline(shaders.waveform_frag)};
+ pub const spectrum = [_]gpu.Pipeline{viewPipeline(shaders.spectrum_frag)};
+ pub const spectrogram = [_]gpu.Pipeline{viewPipeline(shaders.spectrogram_frag)};
+};
+
+/// The analyses, over `samples` samples of a read-only buffer from `offset`
+/// (see each `layouts.*Params`): waveform columns ([4]f32 each, a group per
+/// column), the spectrogram's levels (`rows` per column, a group per
+/// column) and the spectrum's columns ([2]f32 each, one group, with an FFT
+/// scratch buffer of `layouts.fft_size * 2` [2]f32 before them).
+pub const kernels = struct {
+ pub const waveform: gpu.Kernel = .{ .code = shaders.waveform_comp, .readonly_buffers = 1, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 64, 1, 1 } };
+ pub const spectrogram: gpu.Kernel = .{ .code = shaders.spectrogram_comp, .readonly_buffers = 1, .readwrite_buffers = 1, .uniform_buffers = 1, .threads = .{ 256, 1, 1 } };
+ pub const spectrum: gpu.Kernel = .{ .code = shaders.spectrum_comp, .readonly_buffers = 1, .readwrite_buffers = 2, .uniform_buffers = 1, .threads = .{ 256, 1, 1 } };
+};
test "the history keeps the newest samples in order" {
var s: Scope = .{};
@@ -392,3 +429,13 @@ test "frequencies place on a log axis" {
try std.testing.expectEqual(@as(f32, 0), place(min_freq, 48_000));
try std.testing.expectApproxEqAbs(@as(f32, 1), place(20_000, 48_000), 1e-6);
}
+
+test "notes and frequencies convert both ways" {
+ try std.testing.expectApproxEqAbs(@as(f32, 69), midi(440, 440), 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 40), midi(82.4069, 440), 1e-3);
+ try std.testing.expectApproxEqAbs(@as(f32, 261.626), hz(60, 440), 1e-2);
+ try std.testing.expectApproxEqAbs(@as(f32, 69), midi(442, 442), 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 61.5), midi(hz(61.5, 432), 432), 1e-4);
+ try std.testing.expectEqualStrings("A", note_names[@mod(69, 12)]);
+ try std.testing.expectEqualStrings("C", note_names[@mod(60, 12)]);
+}