Logue SDK 2.0 のAPI:新たなパラメータ表示方法の詳細解説



logue SDK 2.0では、ユーザユニットで利用できるパラメータの個数が従来の6個から24個に増え、表示方法を様々にコントロールできるようになりました。これはプラグインのユーザインタフェースがの大幅な改善ですが、いろいろ機能が増えているので、ドキュメントにある記載を少し嚙み砕いてここにまとめておきます。

基本事項

実際のパラメータの型は常に符号付き16ビット整数(int16)です。
ノブを右に回すと値が1増え、左に回すと値が1減ります。
これは表示方法とは関係なく、常に同じです。

パラメータには「最小値(min)、最大値(max)、初期値(init)」が必要です。
負の数値も利用可能で、minが負の場合は「中央値(center)」を定めることができます。ただし、現時点ではcenterの値は0にしか設定できない(それ以外の値にしても、中央値は0として動作する)
これらもすべてint16です。

ノブを動かすとminとmaxの範囲で実際の値(表示される値ではなく、ユーザユニットに渡されるint16の値)が変化します。
ノブを動かす前の状態では、表示される値はinitになっていますが、実際にユーザユニットに値が渡されるのはノブを動かした時です。

1つのパラメータを表す構造体の定義は以下の通りです。パラメータの設定値をこの順にheader.cの中で記述します。

typedef struct unit_param {
 int16_t min;
 int16_t max;
 int16_t center;
 int16_t init;
 uint8_t type;
 uint8_t frac : 4;       // fractional bits / decimals according to frac_mode
 uint8_t frac_mode : 1;  // 0: fixed point, 1: decimal
 uint8_t reserved : 3;
 char name[UNIT_PARAM_NAME_LEN + 1];
} unit_param_t;

固定小数点数

パラメータは16ビット符号あり整数ですが、固定小数点数として表示させることができます。
fracを1以上(最大16)にすると、表示が小数点数になります。

表示方法はfrac_modeが0か1かで変わります。

frac_modeが0の場合、数値は固定小数点数として扱われます。
この場合、fracの値が小数部分を表すビット数になります。
従って、パラメータの整数値を\(n\)とするとスクリーンに表示される数値は\(n/2^{frac}\)になります。

例えば、実際の数値が1,2,3,4,5のとき、スクリーンに表示される数値はfracの値によって以下のように変わります。

\(n\) 1 2 3 4 5
frac = 0 1 2 3 4 5
frac = 1 0.5 1 1.5 2 2.5
frac = 2 0.25 0.5 0.75 1 1.25
frac = 3 0.125 0.25 0.375 0.5 0.625

十進固定小数点数

frac_modeが1の場合、スクリーンに表示される数値は、パラメータの整数値を\(n\)とすると\(n/(10*{frac})\)になります。

例えば、実際の数値が1,2,3,4,5のとき、スクリーンに表示される数値はfracの値によって以下のように変わります。

\(n\) 1 2 3 4 5
frac = 0 1 2 3 4 5
frac = 1 0.1 0.2 0.3 0.4 0.5
frac = 2 0.05 0.1 0.15 0.2 0.25
frac = 3 0.033 0.067 0.100 0.133 0.167

表示方法の指定

typeの値によって、以下のような表示方法を指定することができます。

・数値の後ろに単位を表示する
・数値の正負に別の意味を与え、それを表す記号を数値の前に表示する
・数値+1を表示する
・数値を他の文字列に変換して表示する

以下、順番に解説します。

数値+単位

数値の後ろに単位を表す文字が付きます。
以下、:の前がtypeに指定する値で、:の後が実際の表示形式です。
123のところには任意の数値が入ります。正負あり、前述の小数点数もありです。

k_unit_param_type_none:123
k_unit_param_type_percent:123%
k_unit_param_type_db:123dB
k_unit_param_type_cents:123C
k_unit_param_type_semi:123
k_unit_param_type_oct:123
k_unit_param_type_hertz:123Hz
k_unit_param_type_khertz:123kHz
k_unit_param_type_bpm:123
k_unit_param_type_msec:123ms
k_unit_param_type_sec:123s

none、semi、oct、bpmは現時点では同じように表示されますが、将来的に、例えばアイコンが付くなどの拡張があるのかもしれません。

正負以外の符号を付ける

数値の前後に文字を付けて、正負とは異なる意味を表現します。

k_unit_param_type_drywet
負の数値はWet、0はBalance、正の数値はDryを表すW,BAL,Dを付与します。
また、WetとDryはそれぞれ「値-min」「値-max」の数値を表示ます。min=-100、max=100の場合、

実際の値 表示
-100 W0
-1 W99
0 BAL
1 D99
100 D0

となります。

k_unit_param_type_pan:負の値は「L数値%」、0は「C」、正の値は「R数値%」と表示されます。

k_unit_param_type_spread:負の値は「<数値%」、0は「0%」、正の値は「>数値%」と表示されます。

最小値が1になるように換算した数値を表示する

k_unit_param_type_enum

min\(=n\)のとき、「\(値-n+1\)」を表示します。
単位はありません。小数点表示の場合は、「\(値-n+1\)」を指定した方法で小数点数に変換します。

例えばmin=0の場合、「実際の値+1」の数値を表示します。
配列の添字は0で始まりますが、添字0の要素を「1番目の要素」と数えることがありますので、そういった内部表現とユーザ向けの表現との整合を取るには便利だと思われます。

数値を他のものに変換して表示する

k_unit_param_type_strings

数値に対応する文字列を表示します。

パラメータ番号と値を受け取り、スタティックな文字列を返す関数
const char * unit_get_param_str_value(uint8_t id, int32_t value)
を定義しておく必要があります。SDKで提供されているテンプレートでは、パブリックメソッド
const char * getParameterStrValue(uint8_t index, int32_t value)
に処理を追加します。

k_unit_param_type_bitmaps

数値に対応する16×16ピクセルのビットマップを表示します。

パラメータ番号と値を受け取り、ビットマップを表すスタティックな配列を返す関数
const uint8_t * unit_get_param_bmp_value(uint8_t id, int32_t value)
を定義しておく必要があります。SDKで提供されているテンプレートでは、パブリックメソッド
const uint8_t * getParameterBmpValue(uint8_t index, int32_t value)
に処理を追加します。

k_unit_param_type_onoff

値が0のとき「off」、1のとき「on」を表示します。

k_unit_param_type_midi_note

数値をノート番号とみなして、音名を表示します。

まとめ

logue SDK 2.0ではパラメータの表示方法をいろいろ選べるようになりました。
小数点数が使えるようになり、単位の表示と、パンやスプレッド、ドライ・ウエットなどについて専用の表示が用意されました。
さらに、文字列や白黒アイコンを使った独自の表示方法までもが利用できるようになりました。

本来の使い方とは違いますが、任意の文字列を設定できるパラメータはデバッグにも役立ちそうですし、任意のビットマップを設定できるパラメータは16×16 bitの情報を出力できますので、変数の値をビットパターンで確認するためにも使えそうです。

一方、パラメータ名として表示できる字数は減り(11文字→7文字)、英小文字が使えなくなりました。
これは物理的に表示領域が減ってしまったので、やむを得ないですね。

なお、冒頭の写真のパラメータの定義は以下のようになっています。

{-200, 200, 0, 0, k_unit_param_type_msec, 0, 0, 0, {"Delay"}},
{-200, 200, 0, 0, k_unit_param_type_pan, 1, 0, 0, {"Pan"}},
{-100, 100, 0, 0, k_unit_param_type_drywet, 0, 0, 0, {"Wet/Dry"}},
{1, 10000, 0, 0, k_unit_param_type_khertz, 1, 1, 0, {"Cutoff"}},

コメント