"ext_obex.c" はまた、t_atom の値の get や set のために使う、いくつかの新しい atom ユーティリティを提供しています。t_atom への直接のアクセスは引き続きサポートされますが、多くの開発者はこれらのユーティリティがより簡潔で、安全であることがわかるでしょう。
atom_setlong |
||
| 整数の値を t_atom に挿入し、t_atom の型を A_LONGに変更するために、atom_setlong 関数を使います。 | ||
| t_max_err atom_setlong(t_atom *a, long b); | ||
| a | 値と型を修正される t_atom へのポインタ | |
| b | t_atom にコピーされる整数の値 | |
このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_setfloat |
||
| 浮動小数点の値を t_atom に挿入し、t_atom の型を A_FLOATに変更するために、atom_setfloat 関数を使います。 | ||
| t_max_err atom_setfloat(t_atom *a, double b); | ||
| a | 値と型を修正される t_atom へのポインタ | |
| b | t_atom にコピーされる浮動小数点の値 | |
このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_setsym |
||
| t_symbol *を t_atom に挿入し、t_atom の型を A_SYMに変更するために、atom_setsym 関数を使います。 | ||
| t_max_err atom_setsym(t_atom *a, t_symbol *b); | ||
| a | 値と型を修正される t_atom へのポインタ | |
| b | t_atom にコピーされる t_symbol へのポインタ | |
このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_setobj |
||
| 汎用のポインタの値を t_atom に挿入し、t_atom の型を A_OBJに変更するために、atom_setobj 関数を使います。 | ||
| t_max_err atom_setobj(t_atom *a, void *b); | ||
| a | 値と型を修正される t_atom へのポインタ | |
| b | t_atom にコピーされるポインタの値 | |
このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_getlong |
||
| t_atom から long 整数の値を取得するために、atom_getlong 関数を使います。 | ||
| long atom_getlong(t_atom *a); | ||
| a | 値を取得される t_atom へのポインタ | |
このルーチンは、可能であれば指定された t_atom の値を、整数として返します。そうでない場合、０を返します。 t_atom が、関数で指定された型でない場合、このルーチンは、t_atom からの有効な値を強制的に型変換しようとします。例えば、t_atom atの値が 3.7、型が A_FLOATにセットされている場合、atom_getlong 関数は、 at の小数点以下を切り捨てられた整数(int)の値 3 を返します。このルーチンは、t_symbol データも強制型変換しようとします。 |
||
atom_getfloat |
||
| t_atom から 浮動小数点数の値を取得するために、atom_getfloat 関数を使います。 | ||
| float atom_getfloat(t_atom *a); | ||
| a | 値を取得される t_atom へのポインタ | |
このルーチンは、可能であれば指定された t_atom の値を、浮動小数点数として返します。そうでない場合、０を返します。t_atom が、関数で指定された型でない場合、このルーチンは、t_atom からの有効な値を強制的に型変換しようとします。例えば、t_atom atの値が 5、型 が A_LONGにセットされている場合、 atom_getfloat 関数は、at の値を 浮動小数点数 (float) として、または 5.0 を返します。このルーチンは、t_symbol データも強制的に型変換しようとします。 |
||
atom_getsym |
||
| t_atom から t_symbol * の値を取得するために、atom_getsym 関数を使います。 | ||
| t_symbol *atom_getsym(t_atom *a); | ||
| a | 値を取得される t_atom へのポインタ | |
このルーチンは、可能であれば指定された A_SYM型 のt_atom の値を返します。そうでない場合、 gensym("") 、あるいは_sym_nothing と同じような、有効な t_symbol * として空の値を返します。データ型が合わない場合、強制的な型変換を行なおうとはしません。 |
||
atom_getobj |
||
| t_atom から 一般的なポインタの値を取得するために、atom_getobj 関数を使います。 | ||
| void *atom_getobj(t_atom *a); | ||
| a | 値を取得される t_atom へのポインタ | |
このルーチンは、可能であれば指定された A_OBJ型 のt_atom の値を返します。そうでない場合、NULL を返します。データ型が合わない場合、強制的な型変換を行なおうとはしません。 |
||
atom_getcharfix |
||
| t_atom から、 0〜255 の符号なし整数（unsigned integer）の値をを取得するために、atom_getcharfix 関数を使います。 | ||
| long atom_getcharfix(t_atom *a); | ||
| a | 値を取得される t_atom へのポインタ | |
このルーチンは、可能であれば、指定された t_atom の値を 0〜255 の間の整数値として返します。そうでない場合 0 を返します。t_atom が long 型で、そのデータが 0〜255 の範囲を超えてしまう場合には、データはこの範囲内に切り捨てられてから出力されます。t_atom が float 型の場合、浮動小数点数の値は255を掛けられ、その後、0〜255 の範囲に切り捨てられてから出力されます。例えば、浮動小数点数 0.5 は、127 ( 0.5* 255.) として、atom_getcharfix から出力されます。t_symbol データの場合は、強制的な型変換を行なおうとはしません。 |
||
atom_arg_getlong |
||
| atom が存在する場合、atom リストから、特定の t_atom の整数値を取得するために atom_arg_getlong 関数を使います。 | ||
| t_max_err atom_arg_getlong(long *c, long idx, long ac, t_atom *av); | ||
| c | この関数が成功した場合に、atom のデータを取得するための long 変数へのポインタ。 | |
| idx | atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの３番目の atom からのデータが欲しい場合、idx は２にセットされなければなりません。 | |
| ac | avの数 | |
| av | atomリストの最初の t_atom へのポインタ | |
このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 関数が成功した場合、atom_arg_getlong 関数は c の値を変更するだけです。例えば、次のコードの断片は、シンプルな、しかし典型的な使用の例を示しています。 void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av) { long var = -1; // ここに, 0 またはそれ以上の値が期待されます atom_arg_getlong(&var, 0, ac, av); if (val == -1) // i.e. unchanged post("it is likely that the user did not provide a valid argument"); else { ... } } |
||
atom_arg_getfloat |
||
| atom が存在する場合、atom リストから、特定の t_atom の浮動小数点数の値を取得するために atom_arg_getfloat 関数を使います。 | ||
| t_max_err atom_arg_getfloat(float *c, long idx, long ac, t_atom *av); | ||
| c | この関数が成功した場合に、atom のデータを取得するための float 変数へのポインタ。そうでない場合は、この値は変更されないままです。 | |
| idx | atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの３番目の atom からのデータが欲しい場合、idx は２にセットされなければなりません。 | |
| ac | avの数 | |
| av | atomリストの最初の t_atom へのポインタ | |
このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_arg_getdouble |
||
| atom が存在する場合、atom リストから、特定の t_atom の浮動小数点数の値を double として取得するために atom_arg_getdouble 関数を使います。 | ||
| t_max_err atom_arg_getdouble(double *c, long idx, long ac, t_atom *av); | ||
| c | この関数が成功した場合に、 atom のデータを取得するための double 変数へのポインタ。そうでない場合は、この値は変更されないままです。 | |
| idx | atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの３番目の atom からのデータが欲しい場合、idx は２にセットされなければなりません。 | |
| ac | avの数 | |
| av | atomリストの最初の t_atom へのポインタ | |
このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 |
||
atom_arg_getsym |
||
| atom が存在する場合、atom リストから、特定の t_atom の t_symbol * を取得するために atom_arg_getsym 関数を使います。 | ||
| t_max_err atom_arg_getsym(t_symbol **c, long idx, long ac, t_atom *av); | ||
| c | この関数が成功した場合に、atom のデータを取得するためのt_symbol * 変数へのポインタ。そうでない場合は、この値は変更されないままです。 | |
| idx | atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの３番目の atom からのデータが欲しい場合、idx は２にセットされなければなりません。 | |
| ac | avの数 | |
| av | atomリストの最初の t_atom へのポインタ | |
このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。 関数が成功した場合、atom_arg_getsym 関数は c の値を変更するだけです。例えば、次のコードの断片は、シンプルな、しかし典型的な使用の例を示しています。 void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av) { t_symbol *filename = _sym_nothing; // ここに、ファイル名が期待されます。 // 取得できない場合は、ダイアログボックスを開きます。 atom_arg_getsym(&filename, 0, ac, av); if (filename == _sym_nothing) { // 変更されない場合 // ファイルダイアログボックスを開きます // ファイル名として値を取得 } // ファイル名を使って何かを行ないます } |
||