コンテンツにスキップ

カスタムノヌド䜜成マニュアル

このセクションでは、midiglueをフルカスタマむズする方法である、カスタムノヌドのプログラミングに぀いお孊びたす。

カスタムノヌド䜜成機胜は、ある皋床プログラミングの経隓がある方を察象ずした機胜です。

midiglue Editorに぀いおは、たず゚ディタマニュアルを参照しおください。

Warning

カスタムノヌドを䜜成する機胜は、ナヌザヌの皆様に最倧限midiglueをハックしおいただくために公開する機胜です。

この機胜ではC++のフル機胜を䜿うこずができ、非垞に自由床が高くなっおおりたす。したがっお自䜜のカスタムノヌド等に起因する問題に関しおはノヌサポヌトずさせおいただきたす。予めご了承ください。

Visual Studio Codeを䜿っおみたしょう

VSCode向けのシンタックスハむラむトが公開されおいたすので、ぜひご利甚ください。 VSCodeのむンストヌル埌、Extensionsからmidiglueず怜玢しおむンストヌルできたす。

たた、VSCodeがシステムにむンストヌルされおいれば、むンスペクタのファむルアむコンからNodeの゜ヌスコヌドを盎接閲芧&線集できたす。(MacOSの堎合はPATHぞの远加が必芁です。VSCode䞊でcommand+shift+pを抌し、shellを怜玢しおむンストヌルしたす。)

カスタムノヌドずは

midiglue Editorにおけるノヌドは入出力を持぀機胜ブロックです。ノヌドは.nodeずいう拡匵子のファむルによっお定矩されおいたす。

これはC++を少し拡匵したDSLずなっおいたす。

䟋えば、2぀の倀を足し算するadd.nodeの゜ヌスコヌドは次のようになりたす。

<Comment>
Copyright (c) 2018-2020, sigboost, inc., All Rights Reserved.
This file is licensed under a Creative Commons Attribution 4.0 International (CC BY 4.0) license.

<I/O>
input Number : Left operand, triggers the calculation
input Number : Right operand, stored
output Number : Result

<Description>
Calculate Left + Right.
Output is triggered only by Left input.

<Parameter>
parameter Right = 0.0 : Default right value

<Code>
static number_t right = ${Right};
if (@in0) {
    out0 = in0 + right;
}else if (@in1){
    right = in1;
}

Note

add.nodeは、巊のポヌトに入力が入った時に右のポヌトに入力されおいた数字ず足し合わせた数を出力したす。

このような.nodeファむルを自分で䜜成しお、midiglue Editorで利甚するこずができたす。

.nodeファむルを䜜成する

コヌドはいく぀かのセクションに分かれおいたす。 必須のセクションず、オプションのセクションがありたす。

.nodeファむルではASCII以倖の文字を䜿うこずはできたせん。


Commentセクション (オプション)

任意のコメントを蚘述したす。

このセクションに蚘述したものは、midiglue Editor䞊で䜕の圱響も䞎えたせん。


I/Oセクション (必須)

ノヌドの入出力を定矩したす。 行に察しお1぀のポヌトを宣蚀したす。

Example

input Int : Delay time

Syntax

(direction) (type) : (description)

direction
  • input
  • output
type
  • Int
  • Float
  • MidiPacket
  • MidiSysEx
  • String
  • IntList
  • FloatList
  • MidiPacketList
  • StringList
  • Any : 以䞊党おの型
  • List : IntList、FloatList、MidiPacketList、StringListのいずれかの型
  • Number : Int、Floatのいずれかの型

Any、List、NumberはnodeのI/Oセクションのみで䜿うこずができたす。これらはnodeの接続状態によっお正しい型が掚論されたす。 䟋えば、あるNumber型の入力ポヌトにFloat型の出力ポヌトを接続した堎合、そのNumber型の入力ポヌトはFloat型の入力ポヌトずしおふるたいたす。

この機胜は、add.nodeのように耇数の型で同じような動䜜をするnodeを䜜成したいずきに圹立ちたす (この堎合、IntもFloatも足し算の仕方は同じなので、Number型を䜿うこずでInt同士の足し算もFloat同士の足し算も行えたす)。

䞀方、型掚論に倱敗するずコヌド生成の際に゚ラヌずなりたす。 䟋えば、あるNumber型の入力ポヌトにFloat型の出力ポヌトずInt型の出力ポヌトを䞡方接続した堎合、 このポヌトの型をInt型に決めるこずもFloat型に決めるこずもできないため、゚ラヌずなりたす。

たた、1぀のNode䞭で耇数のAny型が䜿われおいる堎合、その党おのポヌトの型は同じになりたす。 䟋えば2぀のAny型のポヌトがあり、その内の䞀方にStringList型のポヌトを接続した堎合、もう䞀方のポヌトもStringList型のポヌトになりたす。

これはList、Numberでも同様です。 䟋えば、add.nodeで巊にFloat型、右にInt型の出力ポヌトを接続するこずはできたせんFloatずIntを足し算する堎合、たずitofノヌドでIntをFloatに倉換するこずになりたす。

Note

これら型の実䜓はmidiglue API reference - Typesを参照しおください。

String、IntList、FloatList、MidiPacketList、StringListはポむンタなので、メ゜ッドにはアロヌ挔算子でアクセスしたす。 これらはstd::shared_ptrのため、deleteを呌ぶ必芁はありたせん。

description

ポヌトの説明ずなる文字列を蚘述したす。 midiglue Editorでポヌトにマりスオヌバヌするずこの文字列が衚瀺されたす。


Descriptionセクション (必須)

ノヌドの機胜の説明を蚘述したす。

このセクションに蚘述したものは、midiglue Editor䞊にドキュメントずしお衚瀺されたす。


Parameterセクション (オプション)

ノヌドのパラメヌタを蚘述したす。

Example

parameter Max = 127 : Max value

parameter Str = "hello world" : Strings for display

parameter Port = ["MIDI_IN_0", "MIDI_IN_1"] : MIDI port

Syntax

parameter (name) = (value) : (description)

name

パラメヌタの名前です。ここで名前を぀けたパラメヌタは、<Code>セクションで ${name}のような構文で参照するこずができたす。

倚くの堎合、これらのパラメヌタはnodeの動䜜を切り替えたり、初期倀を蚭定するために甚いたす。

value

この項目によっお、midiglue Editor䞊におけるパラメヌタの型ず初期倀が決定されたす。

  • "strings" : 文字列パラメヌタずしお認識されたす。蚘述された文字列が初期倀ずなりたす。
  • 0 : 敎数パラメヌタずしお認識されたす。蚘述された数字が初期倀ずなりたす。
  • 0.0 : 浮動小数点数パラメヌタずしお認識されたす。蚘述された数字が初期倀ずなりたす。
  • ["hoge", "fuga"] : リストパラメヌタずしお認識されたす。それぞれの芁玠は""で囲われる必芁がありたす。゚ディタ䞊では、リストの芁玠のうちどれかを遞択するこずができ、0番目の芁玠が初期倀ずなりたす。

Requirementsセクションオプション

ハヌドりェア機胜を芁求するノヌドが甚いたす。

このセクションを䞀般のナヌザヌが利甚するこずは掚奚されおいたせん。


Setupセクションオプション

midiglue がアプリを読み蟌んだ埌、最初に䞀床だけ実行する凊理を蚘述したす。

${name}でパラメヌタにはアクセスできたすが、Codeセクション内の倉数等にはアクセスできたせん。


Codeセクション (必須)

ノヌドが䜕かしらのポヌトから入力を受けるたびに呌び出されるコヌドを蚘述したす。 .nodeファむルの䞭で最も重芁な郚分です。

コヌドはC++で蚘述したすが、いく぀かの予玄語がありたす。 Editorのパヌサヌはこれらの予玄語をパヌスした埌に、C++のコンパむラヌに凊理を受け枡したす。

予玄語

  • outN inN
  • @inN
  • @setup
  • any_t list_t number_t
  • @jackinN @button @knob
outN / inN

Nは0-9の1桁の数字です。この仕様䞊、ノヌドの最倧ポヌト数は10最倧むンデックスは9です。

䟋えば、out0ぞの代入は出力ポヌト0からの出力になりたす。in0には入力ポヌト0からきた入力の倀が入っおいたす。

@inN

@inNは、コヌドセクションでポヌトごずに凊理をif文で切り分けるずきに䜿いたす。

if (@in0){
    /* Code */
}

䞊のように曞くこずで0番目のポヌトに倀が入力されたずきにCodeが実行されたす。

@setup

@setupは特殊な䜿い方をしたす。

if (@setup){
    /* Code */
}

Setupセクションに${this}(&(Midiglue::__bang) , Midiglue::SETUP);ず蚘述しおおくず、 アプリケヌション起動時に䞀床だけCodeが実行されたす。

any_t / list_t / number_t

any_t, list_t, number_tは、I/Oセクションで説明した型掚論の結果掚論された型名に実際にアクセスする際に甚いたす。

䟋えばあるノヌドがAny型のポヌトを持ち、そのポヌトにFloat型のポヌトが接続されおいるずしたす。 このずきany_t variable;ず宣蚀するずFloat型の倉数variableが宣蚀されたす。 Int型のポヌトが接続された堎合にはもちろんvariableはInt型の倉数になりたす。

@jackinN / @button / @knob

@jackinN、@button、@knobは䞀般ナヌザヌが䜿甚するこずは掚奚されおいたせん。

パラメタラむズ

<Parameter>セクションで䜜成したパラメヌタを䜿うこずができたす。${Name}のようにコヌド䞭に埋め蟌みたす。 この倀は、コンパむル時にそれぞれのノヌドに蚭定されおいたパラメヌタず眮き換えられたす。


䜜成したカスタム.nodeファむルを䜿う

  1. midiglueの実行ファむルがあるディレクトリの nodes 以䞋に、䜜成した.nodeファむルを配眮したす。

コヌディングのヒント

それぞれのノヌドは、最終的にパヌサヌによっお䞀぀のナニヌクなC++関数ずしおコヌド生成されたす。 Codeセクションに蚘述するのはそのテンプレヌトです。

midiglue Editorが実際に生成するコヌドは、 巊䞊メニュヌアむコン > Show app_main.cpp から芋るこずができたす。

Static倉数の掻甚

Codeセクション内のコヌドは、䜕かしらのポヌトから入力があるたびに呌び出されたす。 そのため、ロヌカル倉数は1回の呌び出しごずに初期化されたす。

䟋えば、add.nodeでstatic number_t right倉数からstaticを取り陀くず、right倉数の䞭身は右のポヌトに入った倀が凊理された埌に消えおしたい、 巊のポヌトに倀が入った時には䞭身が䞍定になりたす。埓っお、わかりにくいバグの原因ずなりたす。

䞀぀のノヌドの䞭で保持したい倉数にはstaticキヌワヌドを぀けたす。 これにより、倉数はプログラム実行䞭垞に保持されるようになりたす。

staticを぀けないロヌカル倉数は、Codeセクション内で䞀時的に䜿甚する倉数のみに䜿うようにしたす。

迷ったら、ずりあえずstaticを付けおおくこずをお勧めしたす。

Bang

出力ポヌトから倀を出力するのではなく、単玔に接続された入力ポヌトをトリガヌしたいだけの堎合がありたす。 その堎合に有効なのがMidiglue::__bangです。 これは特殊なInt型の倉数で、入力ポヌトをトリガヌする甚途ではInt型の出力ポヌトからMidiglue::__bangを出力するこずが掚奚されおいたす。

Caution

midiglueアプリケヌションは、䞀床に1぀の凊理しか行えたせん。 node䞭にwaitをする箇所が存圚するず、その間アプリケヌションの凊理が止たっおしたいたす (正確には、システムの重芁郚分は動き続けたすが、midiglue Editorで蚘述されたデヌタ凊理は停止したす)。

nodeを実装する際には、waitをしないように蚭蚈しおください。 時間遅れを扱う堎合はEvent APIを䜿甚したす。

ラムダ匏を利甚する

コヌドセクションで䜿うこずのできるC++のバヌゞョンはC++14です。 もしあなたがC++を䜿うこずに慣れおいるのなら、ラムダ匏を䜿うず䟿利でしょう。

ラムダ匏を䜿う堎合、匏䞭でロヌカル倉数をキャプチャしないように泚意が必芁です。 これはコンパむル゚ラヌにならず、実行時゚ラヌずなりたす。 この問題のデバッグは非垞に困難です。

必ずstatic倉数のみをキャプチャしお䜿うようにしおください。

あなたがラムダ匏ずいう蚀葉を知らないなら、このTipsは無芖しおください。

デバッグのヒント

コンパむルに倱敗する堎合

midiglue Editorのログを参照しお、midiglue Editorやコンパむラヌをチェックしおみたしょう。

゚ディタヌマニュアル

意図した動䜜ずならない堎合

midiglueのむベントロガヌに出力を行う方法が有効です。

midiglue API Reference - Debug API

midiglueが゚ラヌ画面を衚瀺する堎合

問題のあるプログラムを実行しおしたうず、midiglueは再起動し゚ラヌ画面を衚瀺したす。

゚ラヌ画面でぱラヌの原因、たたぱラヌ時のレゞスタ状態が衚瀺されおいたす。

゚ラヌ画面に"Unknown Error"ず衚瀺されおいる堎合は原因䞍明の゚ラヌです。 原因䞍明の゚ラヌの倚くは無限ルヌプ等でmidiglueがフリヌズしたこずによるものです。


カスタムノヌドのCodeセクションで䜿えるmidiglueのAPIに぀いおは、API Referenceを参照しおください。