Lib UTAU ヘルプ
TUtauSection
最終更新：
libutau
-
view
概要
TUtauSection は、パイプファイルの 1 セクション分のデータを取り扱うクラスです。
パイプファイルから 1 セクション分の内容をパースしたり、プロパティの取得・設定をしたりといった、セクション操作の基礎を提供します。
TUtauSection は、TUtauSectionVersion、TUtauSectionSettings、TUtauSectionNote の基底クラスです。
public static メンバ関数
ReadSectionName()
static status_t ReadSectionName(char** oStream, string* oSectionName);
パイプファイルのデータからセクション名を読み取ります。
TUtauData::SetTo() がこの関数を用います。ユーザーはこの関数を使う必要はありません。
- 引数
- oStream ... パイプファイルの内容を読み込んだバッファへのポインタです。
- oSectionName ... 読み取ったセクション名を格納します。
- 返値
- B_OK ... セクション名を読み取れました。oStream はセクション行の行頭に移動しています。
- B_ERROR ... バッファの末尾までセクション名がありませんでした。oStream はバッファの末尾に移動しています。
SkipSection()
static status_t SkipSection(char** oStream);
1 セクション分、パイプファイルのデータを読み飛ばします。ポインタは、次のセクションの行頭または、バッファの末尾に移動します。
TUtauData::SetTo() がこの関数を用います。ユーザーはこの関数を使う必要はありません。
- 引数
- oStream ... パイプファイルの内容を読み込んだバッファへのポインタです。
- 返値
- B_OK ... 常に B_OK を返します。
public メンバ関数
コンストラクタ
TUtauSection();
初期設定を行います。
デストラクタ
virtual ~TUtauSection();
特段何もしません。
Export()
status_t Export(list<string>* oStringList) const;
変更のあったプロパティとその値を書き出します。
TUtauData::Export() がこの関数を用います。ユーザーはこの関数を使う必要はありません。
- 引数
- oStringList ... エクスポート結果を格納します。
- 返値
- B_OK ... 常に B_OK を返します。
GetDefaultValue()
status_t GetDefaultValue(const string& oKey, string* oValue) const;
プロパティのデフォルト値を取得します。
- 引数
- oKey ... デフォルト値を取得したいプロパティの名前。
- oValue ... 取得したデフォルト値を格納する変数。
- 返値
- B_OK ... 正常にデフォルト値を取得できました。
- B_NAME_NOT_FOUND ... デフォルト値が用意されていない oKey が渡されました。
GetValue()
status_t GetValue(const string& oKey, string* oValue, bool* oIsDefault = NULL) const;
status_t GetValue(const string& oKey, int32* oValue, bool* oIsDefault = NULL) const;
status_t GetValue(const string& oKey, double* oValue, bool* oIsDefault = NULL) const;
セクションに記述されている各種プロパティを取得します。
セクションには、
Key=Value
の形で様々なプロパティが記述されており、GetValue() 関数でその値を取得できます。第 2 引数で渡す変数の型によって、取得する値のその型に合わせて変換できます。
- 引数
- oKey ... プロパティの名前です。例えば、TUtauSection の派生クラスである TUtauSectionNote で、"Length" という名前のプロパティを扱う時は、oKey に "Length" を渡します。ただし、"Length" という文字列リテラルを渡すよりは、Lib UTAU で定義されている KEY_NAME_LENGTH を用いる方がスマートです。
- oValue ... 取得したプロパティの値を格納する変数です。値を文字列で取得したい場合は string 型、値を整数で取得したい場合は int32 型、値を浮動小数で取得したい場合は double 型の変数を渡します。
- oIsDefault ... 取得した値がデフォルト値かどうかを格納する変数です。GetValue() 関数は、パイプファイルにプロパティが記述されていなくても、UTAU で用いられるであろうデフォルト値を推定して値を取得ことがあります（例えば、原音設定の先行発声を返すなど）。デフォルト値を推定して値を取得した場合、oIsDefault に true を格納します。
- 返値
- B_OK ... 正常にプロパティの値を取得できました。
- B_NAME_NOT_FOUND ... セクション内に oKey が記述されておらず、oKey に対応するデフォルト値もありませんでした。
MakeDefault()
status_t MakeDefault(const string& oKey);
プロパティの値をデフォルト値にします。
注意点として、プロパティがデフォルト値になるのは Lib UTAU の中だけであり、パイプファイルに書き戻した後、UTAU 本体がデフォルト値として扱ってくれるかどうかはプロパティによります。
- 引数
- oKey ... デフォルト値にしたいプロパティの名前です。
- 返値
- B_OK ... 常に B_OK を返します。
Parent()
const TUtauData* Parent() const;
TUtauData* Parent();
セクションを統括する TUtauData へのポインタを取得します。
- 返値
- セクションを統括する TUtauData へのポインタ。
Revert()
status_t Revert(const string& oKey);
プロパティの値を、UTAU 本体から渡された値に戻します。
- 引数
- oKey ... 値を戻したいプロパティの名前です。
- 返値
- B_OK ... 正常に値を戻せました。
- B_NAME_NOT_FOUND ... プロパティ oKey は UTAU 本体から渡されていません。
SectionName()
string SectionName() const;
セクション名を取得します。
- 返値
- セクション名。
SetParent()
status_t SetParent(TUtauData* oParent);
セクションを統括する TUtauData へのポインタを設定します。
TUtauData がこの関数を用います。ユーザーはこの関数を使う必要はありません。
- 引数
- oParent ... TUtauData へのポインタです。
- 返値
- B_OK ... 常に B_OK を返します。
SetSectionName()
virtual status_t SetSectionName(const string& oSectionName);
セクション名を設定します。
通常、セクション名を設定することに意味はありませんが、セクションの挿入や削除をしたい場合は、セクション名を SECTION_NAME_INSERT や SECTION_NAME_DELETE にする必要があります。
- 引数
- oSectionName ... 新しいセクション名です。
- 返値
- B_OK ... 常に B_OK を返します。
SetTo()
virtual status_t SetTo(char** oStream);
パイプファイルのデータを 1 セクション分読み込みます。
TUtauData がこの関数を用います。ユーザーはこの関数を使う必要はありません。
- 引数
- oStream ... パイプファイルの内容を読み込んだバッファへのポインタです。
- 返値
- B_OK ... セクションを読み取れました。oStream は次のセクションの先頭またはバッファの末尾に移動しています。
- B_ERROR ... 何らかのエラーが発生しました。
SetValue()
status_t SetValue(const string& oKey, const string& oValue);
status_t SetValue(const string& oKey, int32 oValue);
status_t SetValue(const string& oKey, double oValue);
プロパティの値を設定します。
- 引数
- oKey ... プロパティの名前です。
- oValue ... プロパティに設定したい値です。いくつかの型を選ぶことができ、値を文字列で設定したい場合は string 型、値を整数で設定したい場合は int32 型、値を浮動小数で設定したい場合は double 型で渡して下さい。整数リテラルを渡すと、コンパイル時、int32 と double の間で曖昧さが解決できずエラーになるので、static_cast<int32> で明示的に型を指定するなどしてください。
- 返値
- B_OK ... 常に B_OK を返します。
public メンバ変数
public メンバ変数はありません。
設計思想
UTAU 本体がパイプファイルを差分管理しており、変更点だけをパイプファイルに返せば良い仕様となっているため、TUtauSection では、セクションの変更を把握できる仕組みを内部で持っています。
パイプファイルからの入力について、
- パイプファイルから受け取ったプロパティ
- パイプファイルから受け取っていないプロパティ
を区別できるように管理しています。
また、パイプファイルへの出力のために、
- UTAU 本体から受け取ったプロパティの値を変更していない
- プロパティの値を変更した or 新たにプロパティの値を設定した
- プロパティの値をデフォルト値にした
を区別できるように管理しています。
また、プロパティの取得の際、利便性のために、値が設定されていなくてもデフォルト値を返しますが、デフォルト値であることを区別できるようにしています（GetValue() の oIsDefault 引数）。
