Aqualeadでの各種ルール


Aqualeadの関数は、いくつかのルールに基づいて実装しています。 このルールを覚えておくことにより、使ったことのない関数でも迷わずに使うことが出来るようになります。

1. 生成と破棄について

Aqualeadのクラスを生成するためにはnewを使わず、Create関数、またはその派生関数(CreateTry等)を使用します。 破棄する時は、ALUpdaterとそのサブクラスのみDestroy関数を使用し、それ以外はRelease関数を使用します。

例外は、各種構造体と、ALProp、ALField、ALMaterial、ALResourceDefine、 スクリプトの値を保持するクラス(ALVariant、ALVariantArray、ALVariantDic)、 ハンドルを使用するALHandleBaseのサブクラス(ALFade、ALVoice等)です。 これらはポインタを使用せず、実体をそのままスタック上に生成して使用します。

そのため、Aqualeadで定義しているクラス・構造体に関してはnew,deleteは使用しません。

2. 参照カウントについて

Aqualeadでは一部のクラス(ALCollisionのサブクラス,ALControllerのサブクラス)を除き、 クラスのインスタンスを関数に渡すと、必ずそのインスタンスの参照カウントが増えるかコピーが行われます。 そのため、関数に渡したインスタンスもReleaseを実行して解放する必要があります。

このReleaseを実行するのは、そのインスタンスが不要になったタイミングではなく、 渡した直後で問題ないため、各種のインスタンスを渡す関数には SetRelease等のReleaseと関数名に付いているバリエーションが存在することがあります。 このような関数を使用することで、解放を設定した先のクラスに任せることが可能になります。

このRelease系の関数は、Releaseを付いていない関数を実行し、直後にそのインスタンスにReleaseを実行したのと等価です。 なお、Release系関数はNULLを渡すとアサートが発生します。

3. 関数の失敗について

Aqualeadでは、関数が失敗するとエラーは通知をせずにアサートを発生させます。 これは引数の間違いや、処理が出来ない場合も全てです。

これにより、例えばポインタが返り値の関数などは、 返り値のNULLチェック等は必要なくなります。

ただし、物によっては失敗を検知したい場合があるため、~~Try系の関数が定義している場合があります。 Try系の関数はアサートを発生させず、成功失敗を返り値として返します。 返り値はboolかポインタで、boolの場合はtrueで成功、falseで失敗、 ポインタの場合は、NULLが失敗になります。

例外として、Findという名称が付いている関数は、 検索失敗が通常動作として発生するため、失敗してもアサートは発生しません。

4. 数学系構造体の動作について

Aqualeadの数学系構造体は、計算結果の構造体を出力せずに、自分自身を書き換える動作を基本とします。 そのため、演算子のオーバーロードは定義しておらず、Mul等の関数を使用します。 これは、計算時の無駄なコピーを抑制するためです。

数学系構造体は、ある程度の相互変換が可能になっていますが、 これらもコンストラクタで明示するか、Assign関数を明示的に呼び出す必要があります。 これも意図しない自動変換が発生しないようにするためです。

また、一部のクラスの関数では数学系の構造体を返り値として使用することがあります。 この構造体はシステム内部のワーク用リングバッファ上に確保してあり、 解放の必要はありませんが、長く保持すると値が変化する可能性があります。 長く保持したい場合はコピーを行う必要があります。 なお、目安として1関数内で完結し、ALYieldなどで中断しない限りはコピーを行う必要はありません。

5. 引数の順番について

引数の順番については、大体の法則が存在しています。

まず、ポインタ引数を使用して返り値を渡すことがあれば、それは必ず先頭に来ます。

次に、例えばインデックスを使用して値を書き込むような場合など、 位置と値を使用する場合、位置が先に、値がその次に来ます。 ただしこれは例外があり、大半の場合位置に0しか使わない場合(ALNodeでのモーションやテクスチャの指定等)は 引数の最後になり、省略可能になります。

それ以外では、意味的に優先度が高い物が前に来て、優先度が低く省略可能な物は後ろに来ます。

6. インスタンスを返す関数での解放の必要について

各種インスタンスを返す関数がありますが、返されたインスタンスを解放する必要があるかどうかは、 関数名にCreateが含まれているかで判断します。ただし、例外としてClone関数もCreate系関数と同様の扱いになります。

Createが含まれている関数で返されたインスタンスは、解放が必須になります。 ただし、前述のようにさらに他の関数に渡してReleaseを実行すればそれ以上保持や解放の必要はありません。

Createが含まれていない場合は、そのインスタンスを解放してはいけません。 他の関数に渡すとしても、~~Release系関数を使用しないように注意してください。

7. 文字列を返す関数について

Aqualeadでは文字列を返す関数はNULLを返すことはありません。 該当がないような場合などは、空文字列を返します。

ただし、設定時はNULLも使用可能です。 その場合、必要に応じて内部で空文字列に変換されます。