ChangeModulationBank

ChangeModulationBank is a low-level command that switches the Modulation bank to be played.

API

Rust

ChangeModulationBank {
    bank,
    transition_mode,
};

Python

ChangeModulationBank(
    bank=bank,
    transition_mode=transition_mode,
)

C#

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

Field	Type	Description
bank	ModulationBank	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

ChangeModulationBank is sent after preparing the bank with WriteModulationBuffer + ConfigModulation to switch the playback target.

Rust

use autd3_rs::commands::{ChangeModulationBank, ConfigModulation, WriteModulationBuffer};
use autd3_rs::geometry::{Autd3, Geometry};
use autd3_rs::units::Hz;
use autd3_rs::value::{LoopBehavior, ModulationBank, SamplingConfig, TransitionMode};
use autd3_rs::{Client, ClientConfig};
use autd3_rs_link_nop::Nop;
use autd3_rs_modulation::{SineOption, modulation_buffer, sine};

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

let mut data = modulation_buffer();
sine(150 * Hz, &SineOption::default(), &mut data)?;

let bank = ModulationBank::B0;

let mut builder = client.datagram_builder();
builder.push(WriteModulationBuffer {
    bank,
    offset: 0,
    data: &data,
});
builder.push(ConfigModulation {
    bank,
    config: SamplingConfig::FREQ_4K,
    size: data.len(),
    loop_behavior: LoopBehavior::Infinite,
});
builder.push(ChangeModulationBank {
    bank,
    transition_mode: TransitionMode::Immediate,
});
let frames = builder.build()?;
for frame in &frames {
    client.send_checked(frame).await?;
}

client.close().await?;

Python

import asyncio

from autd3 import Client, ClientConfig
from autd3.commands import ChangeModulationBank, ConfigModulation, WriteModulationBuffer
from autd3.geometry import Autd3, Geometry
from autd3.units import Hz
from autd3.value import LoopBehavior, ModulationBank, SamplingConfig, TransitionMode
from autd3_link_nop import Nop
from autd3_modulation import SineOption, modulation_buffer, sine


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())

    data = modulation_buffer()
    sine(150.0 * Hz, SineOption(), data)

    bank = ModulationBank.B0

    builder = client.datagram_builder()
    builder.push(
        WriteModulationBuffer(
            bank=bank,
            offset=0,
            data=data,
        )
    )
    builder.push(
        ConfigModulation(
            bank=bank,
            config=SamplingConfig.FREQ_4K,
            size=len(data),
            loop_behavior=LoopBehavior.Infinite,
        )
    )
    builder.push(
        ChangeModulationBank(
            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 data = Modulation.ModulationBuffer();
Modulation.Sine(150 * Hz, new SineOption(), data);

var bank = ModulationBank.B0;

var builder = client.DatagramBuilder();
builder.Push(new WriteModulationBuffer(
    bank: bank,
    offset: 0,
    data: data
));
builder.Push(new ConfigModulation(
    bank: bank,
    config: SamplingConfig.Freq4k,
    size: (uint)data.Length,
    loopBehavior: LoopBehavior.Infinite
));
builder.Push(new ChangeModulationBank(
    bank: bank,
    transitionMode: TransitionMode.Immediate
));
var frames = builder.Build();
foreach (var frame in frames)
{
    await client.SendCheckedAsync(frame);
}

await client.CloseAsync();