ループと遷移

FociStm / PatternStm は, デフォルトでは同じパターン列を無限に繰り返し再生する. 再生回数を有限にする場合は以下の通り.

有限ループ

再生回数は FociStmOption などの loop_behavior で指定する. LoopBehavior::Infinite (デフォルト) は無限ループ, LoopBehavior::Finite(n) は n 回 (最大65535回) 再生して停止する. なお, 停止時は最後のパターンが出力され続ける.

重要な点として, 有限ループは現在と異なるバンクへ切り替えたときに初めて機能する.

// Play the circular motion only 3 times, then stop.
// A finite loop (and non-immediate transition) only fires when switching to a
// different bank, so write to bank B1 instead of the current B0.
let mut builder = client.datagram_builder();
builder.push(FociStm::new(
    50.0 * Hz,
    &foci,
    FociStmOption {
        loop_behavior: LoopBehavior::Finite(NonZeroU16::new(3).unwrap()),
        bank: PatternBank::B1,
        transition_mode: TransitionMode::SyncIdx,
        ..Default::default()
    },
));
for frame in &builder.build()? {
    client.send_checked(frame).await?;
}

# Play the circular motion only 3 times, then stop.
# A finite loop (and non-immediate transition) only fires when switching to a
# different bank, so write to bank B1 instead of the current B0.
builder = client.datagram_builder()
builder.push(
    FociStm(
        50.0 * Hz,
        foci,
        FociStmOption(
            loop_behavior=LoopBehavior.Finite(3),
            bank=PatternBank.B1,
            transition_mode=TransitionMode.SyncIdx,
        ),
    )
)
for frame in builder.build():
    await client.send_checked(frame)

// Play the circular motion only 3 times, then stop.
// A finite loop (and non-immediate transition) only fires when switching to a
// different bank, so write to bank B1 instead of the current B0.
var builder = client.DatagramBuilder();
builder.Push(new FociStm(
    50.0f * Hz,
    foci,
    new FociStmOption(
        bank: PatternBank.B1,
        loopBehavior: LoopBehavior.Finite(3),
        transitionMode: TransitionMode.SyncIdx
    )
));
foreach (var frame in builder.Build())
{
    await client.SendCheckedAsync(frame);
}

遷移タイミング

再生対象のバンクへ切り替えるタイミングは transition_mode で指定する. 使用できるモードは, 遷移先バンクのループ設定 (loop_behavior) によって制限される.

遷移先が無限ループのとき使用できるモード.

Immediate (デフォルト): 書き込み後, 直ちにバンクを切り替える.
Ext: 拡張モード. バンク内の再生が終わると次のバンクへ自動で切り替わる.

遷移先が有限ループのとき使用できるモード.

SyncIdx: 切り替え対象バンクの再生インデックスが 0 に戻ったタイミングで切り替える.
SysTime(DcSysTime): 指定した DC システム時刻に切り替える.
Gpio(GpioIn): 指定した GPIO 入力ピンのトリガで切り替える.

ループ設定と同様, 遷移タイミングもバンクを切り替えたときにのみ作用する.

あらかじめ別バンクへ次の出力を仕込んでおき, 任意のタイミングで切り替える, などの細かい制御を行う場合は, API リファレンスの低レベルコマンドを参照されたい.