Bank Switching

As explained in Moving the Focal Point, in AUTD3 a Pattern and the like are overwritten each time they are sent, and this write is not buffered. As a result, overwriting data that is being played back can cause unintended intermediate data to be output partway through the write.

To prevent this, the AUTD3 Pattern has multiple memory regions (called banks). By writing to a bank that is not currently being played back and then switching the playback target to that bank after the write completes, the data can be swapped without disturbing the output.

Writing to a specified bank

The write-target / playback-target bank is specified with Pattern::with_bank. Pattern::new (when the bank is omitted) uses PatternBank::B0.

In the example below, focus A is first written to B0 and played back, and the next focus B is written to B1, which is not being played back. The output of B0 is not disturbed even while writing to B1, and after the write completes it switches to B1.

Rust

// Write focus A to bank B0 and play it.
let target_a = geometry.center() + offset(0.0 * mm, 0.0 * mm, 150.0 * mm);
let mut pat_a = geometry.pattern_buffer();
autd3_rs_pattern::focus(
    &geometry,
    target_a,
    wavelength,
    &autd3_rs_pattern::FocusOption::default(),
    &mut pat_a,
);
let mut builder = client.datagram_builder();
builder.push(Pattern::with_bank(PatternBank::B0, &pat_a));
for frame in &builder.build()? {
    client.send_checked(frame).await?;
}

// Write focus B to bank B1, which is not currently playing, then switch to B1.
// B0 keeps playing cleanly while B1 is being written (double buffering).
let target_b = geometry.center() + offset(0.0 * mm, 30.0 * mm, 150.0 * mm);
let mut pat_b = geometry.pattern_buffer();
autd3_rs_pattern::focus(
    &geometry,
    target_b,
    wavelength,
    &autd3_rs_pattern::FocusOption::default(),
    &mut pat_b,
);
let mut builder = client.datagram_builder();
builder.push(Pattern::with_bank(PatternBank::B1, &pat_b));
for frame in &builder.build()? {
    client.send_checked(frame).await?;
}

Python

# Write focus A to bank B0 and play it.
target_a = geometry.center() + np.array([0.0, 0.0, 150.0])
pat_a = geometry.pattern_buffer()
pattern.focus(
    geometry,
    target_a,
    wavelength,
    pattern.FocusOption(),
    pat_a,
)
builder = client.datagram_builder()
builder.push(Pattern(pat_a, bank=PatternBank.B0))
for frame in builder.build():
    await client.send_checked(frame)

# Write focus B to bank B1, which is not currently playing, then switch to B1.
# B0 keeps playing cleanly while B1 is being written (double buffering).
target_b = geometry.center() + np.array([0.0, 30.0, 150.0])
pat_b = geometry.pattern_buffer()
pattern.focus(
    geometry,
    target_b,
    wavelength,
    pattern.FocusOption(),
    pat_b,
)
builder = client.datagram_builder()
builder.push(Pattern(pat_b, bank=PatternBank.B1))
for frame in builder.build():
    await client.send_checked(frame)

C#

// Write focus A to bank B0 and play it.
var targetA = geometry.Center + new Vector3(0.0f, 0.0f, 150.0f);
var patA = geometry.PatternBuffer();
Pattern.Focus(
    geometry,
    targetA,
    wavelength,
    new FocusOption(),
    patA
);
var builder = client.DatagramBuilder();
builder.Push(new Pattern(PatternBank.B0, patA));
foreach (var frame in builder.Build())
{
    await client.SendCheckedAsync(frame);
}

// Write focus B to bank B1, which is not currently playing, then switch to B1.
// B0 keeps playing cleanly while B1 is being written (double buffering).
var targetB = geometry.Center + new Vector3(0.0f, 30.0f, 150.0f);
var patB = geometry.PatternBuffer();
Pattern.Focus(
    geometry,
    targetB,
    wavelength,
    new FocusOption(),
    patB
);
var builder2 = client.DatagramBuilder();
builder2.Push(new Pattern(PatternBank.B1, patB));
foreach (var frame in builder2.Build())
{
    await client.SendCheckedAsync(frame);
}

By writing alternately to the bank that is not being played back in this way, the pattern can be swapped without disturbing the output.

Modulation also has banks, and the write-target bank (ModulationBank) can be specified with Modulation::with_bank.

For finer control over bank writing, configuration, and switching, refer to the low-level commands in the API reference.