ChangePatternBank

ChangePatternBank is a low-level command that switches the Pattern bank to be played.

API

Rust

ChangePatternBank {
    bank,
    transition_mode,
};

Python

ChangePatternBank(
    bank=bank,
    transition_mode=transition_mode,
)

C#

new ChangePatternBank(
    bank: bank,
    transitionMode: transitionMode
);

Field	Type	Description
bank	PatternBank	Destination bank
transition_mode	TransitionMode	Behavior on switching

TransitionMode

Immediate	Immediate
SyncIdx	When the playback index next becomes 0
SysTime(DcSysTime, margin)	At the specified DC system time (margin is optional, see below)
Gpio(GpioIn)	Trigger on the specified GPIO input pin
Ext	Extended mode (automatically switches to the next bank when playback within the bank finishes)
Later	Does not transition (only writes to the bank)

SysTime rejects a time earlier than “now + margin” with a MISS_TRANSITION_TIME error, because the FPGA may miss a transition whose time is too close. The margin defaults to 10 ms.

Later means “only write to the bank, do not transition”. Specifying it as the transition_mode of Modulation / FociStm / PatternStm writes and configures the bank without sending the trailing bank change. Specifying it on ChangeModulationBank / ChangePatternBank themselves, which are the transition commands, is a build-time error. Because Later never transitions, it is also exempt from the LoopBehavior combination constraint.

See GPIO pins for details on Gpio(GpioIn).

When switching to the same bank, the TransitionMode and LoopBehavior settings have no effect. For details on bank operation see the bank switching tutorial.

Example

ChangePatternBank is sent after preparing the bank with WritePatternBuffer + ConfigPattern to switch the playback target.

Rust

use core::num::NonZeroU16;

use autd3_rs::commands::{ChangePatternBank, ConfigPattern, WritePatternBuffer};
use autd3_rs::geometry::{Autd3, Geometry, offset};
use autd3_rs::units::{m, mm, s};
use autd3_rs::value::{LoopBehavior, PatternBank, SamplingConfig, TransitionMode};
use autd3_rs::{Client, ClientConfig};
use autd3_rs_link_nop::Nop;
use autd3_rs_pattern::{FocusOption, focus, wavelength};

let geometry = Geometry::new(vec![Autd3::default()]);
let client = Client::open(&geometry, Nop, ClientConfig::default()).await?;

let mut emissions = geometry.pattern_buffer();
focus(
    &geometry,
    geometry.center() + offset(0.0 * mm, 0.0 * mm, 150.0 * mm),
    wavelength(340.0 * m / s),
    &FocusOption::default(),
    &mut emissions,
);

let bank = PatternBank::B0;

let mut builder = client.datagram_builder();
builder.push(WritePatternBuffer {
    bank,
    index: 0,
    emissions: &emissions,
});
builder.push(ConfigPattern {
    bank,
    config: SamplingConfig::new(NonZeroU16::MAX),
    size: 1,
    loop_behavior: LoopBehavior::Infinite,
});
builder.push(ChangePatternBank {
    bank,
    transition_mode: TransitionMode::Immediate,
});
let frames = builder.build()?;
for frame in &frames {
    client.send_checked(frame).await?;
}

client.close().await?;

Python

import asyncio

import numpy as np

from autd3 import Client, ClientConfig
from autd3.commands import ChangePatternBank, ConfigPattern, WritePatternBuffer
from autd3.geometry import Autd3, Geometry
from autd3.units import m, s
from autd3.value import LoopBehavior, PatternBank, SamplingConfig, TransitionMode
from autd3_link_nop import Nop
from autd3_pattern import FocusOption, focus, wavelength


async def main() -> None:
    geometry = Geometry([Autd3([0.0, 0.0, 0.0], [1.0, 0.0, 0.0, 0.0])])
    client = await Client.open(geometry, Nop(), ClientConfig())

    emissions = geometry.pattern_buffer()
    focus(
        geometry,
        geometry.center() + np.array([0.0, 0.0, 150.0]),
        wavelength(340 * m / s),
        FocusOption(),
        emissions,
    )

    bank = PatternBank.B0

    builder = client.datagram_builder()
    builder.push(
        WritePatternBuffer(
            bank=bank,
            index=0,
            emissions=emissions,
        )
    )
    builder.push(
        ConfigPattern(
            bank=bank,
            config=SamplingConfig(0xFFFF),
            size=1,
            loop_behavior=LoopBehavior.Infinite,
        )
    )
    builder.push(
        ChangePatternBank(
            bank=bank,
            transition_mode=TransitionMode.Immediate,
        )
    )
    frames = builder.build()
    for frame in frames:
        await client.send_checked(frame)

    await client.close()


asyncio.run(main())

C#

using System.Numerics;
using System.Threading.Tasks;
using AUTD3;
using AUTD3.Link;
using Nop = AUTD3.Link.Nop;
using static AUTD3.Units;

var geometry = new Geometry(new[] { new Autd3(Vector3.Zero) });
var client = await Client.OpenAsync(geometry, new Nop(), new ClientConfig());

var emissions = geometry.PatternBuffer();
Pattern.Focus(
    geometry,
    geometry.Center + new Vector3(0.0f, 0.0f, 150.0f),
    Pattern.Wavelength(340.0f * m / s),
    new FocusOption(),
    emissions
);

var bank = PatternBank.B0;

var builder = client.DatagramBuilder();
builder.Push(new WritePatternBuffer(
    bank: bank,
    index: 0,
    emissions: emissions
));
builder.Push(new ConfigPattern(
    bank: bank,
    config: new SamplingConfig(ushort.MaxValue),
    size: 1,
    loopBehavior: LoopBehavior.Infinite
));
builder.Push(new ChangePatternBank(
    bank: bank,
    transitionMode: TransitionMode.Immediate
));
var frames = builder.Build();
foreach (var frame in frames)
{
    await client.SendCheckedAsync(frame);
}

await client.CloseAsync();