バージョン
menu_open

ソース管理プラグインDLLの作成方法

Wwiseソース管理プラグインDLLを作成するには、次の手順を実行する必要があります：

Note.gif
Note: 1つのDLLに複数のプラグインを含むことができます。詳細は エクスポート関数の確立 をご覧ください。

新規プロジェクトの開始

新しいプロジェクトを開始するには、プロジェクトを作成し、このプロジェクトで使用されるエクスポート関数を設定する必要があります。

また、プロジェクトで使用するソース管理インターフェースに慣れる必要があります。

プロジェクトの作成

Visual Studioを使用してプロジェクトを作成するには、次の手順を実行します：

  1. MFC DLL C++ Project を作成。MFC DLL Wizard ダイアログ内で、共有 MFC DLL を使用して DLL タイプを Regular DLL に設定する必要があります。
  2. 新規プロジェクトで、Project Properties ダイアログを開き次の手順を実行します：
  • General Property ページで、Character Set プロパティを Use Unicode Character Set に設定
  • C/C++/General Property ページで、Additional Include Directories プロパティ内のSDKインクルードディレクトリへのパスを追加。

プロジェクトが作成され、Wwise Source Control SDK が使用するよう設定されました。次に、プラグインDLLを管理するために Wwise が使用する関数を作成します。

Tip.gif
Tip: 厳密には、MFC DLL プロジェクトを作成する必要はありません。しかし、これの作成により、特定の文字列およびダイアログ操作が容易になります。MFC DLL を使用しない場合は、SysAllocString 関数が使用できるよう、oleauto.h ヘッダを stdafx.h ファイルに含めるようにしてください。

エクスポート関数の確立

各プラグインDLLは、3つの関数をエクスポートする必要があります：

  • AkSourceControlGetPluginIDList(): すべてのプラグイン ID のリストを取得することにより、DLL に含まれているプラグインリストに Wwise がアクセスできるようにします。
  • AkSourceControlGetPluginInfo(): 特定のプラグインと関連付けられた AK::Wwise::ISourceControl::PluginInfo クラスに Wwise がアクセスできるようにします。
  • AkSourceControlCreatePlugin(): AK::Wwise::ISourceControl オブジェクトのインスタンスを作成します。

これらのエクスポートされた関数のプロトタイプは次のタイプの定義内にあります：

以下は、プラグインを2つ含むプラグインDLLのエクスポート関数の例です：

#include "AK/Wwise/SourceControl/ISourceControl.h"
#include "SamplePlugin.h"

namespace
{
    // FirstSamplePlugin ID = {BD47DF98-1700-4542-A33F-E44705C25AF0}
    static const GUID s_guidFirstSamplePluginID = 
    { 0xbd47df98, 0x1700, 0x4542, { 0xa3, 0x3f, 0xe4, 0x47, 0x5, 0xc2, 0x5a, 0xf0 } };
    
    // SecondSamplePlugin ID = {57168691-2354-4166-82BF-DD07A36C16C6}
    static const GUID s_guidSecondSamplePluginID = 
    { 0x57168691, 0x2354, 0x4166, { 0x82, 0xbf, 0xdd, 0x7, 0xa3, 0x6c, 0x16, 0xc6 } };
}

void __stdcall AkSourceControlGetPluginIDList ( AK::Wwise::ISourceControl::PluginIDList& out_rPluginIDList )
{
    out_rPluginIDList.AddTail( s_guidFirstSamplePluginID ); 
    out_rPluginIDList.AddTail( s_guidSecondSamplePluginID );

}

void __stdcall AkSourceControlGetPluginInfo ( const GUID& in_rguidPluginID, 
    AK::Wwise::ISourceControl::PluginInfo& out_rPluginInfo )
{
    if ( in_rguidPluginID == s_guidFirstSamplePluginID )
    {
        FirstSamplePlugin::GetPluginInfo( out_rPluginInfo );
    }
    else if ( in_rguidPluginID == s_guidSecondSamplePluginID )
    {
        SecondSamplePlugin::GetPluginInfo( out_rPluginInfo );
    }

}

AK::Wwise::ISourceControl* __stdcall AkSourceControlCreatePlugin ( const GUID& in_rguidPluginID )
{
    AK::Wwise::ISourceControl* pSourceControl = NULL;

    if ( in_rguidPluginID == s_guidFirstSamplePluginID )
    {
        pSourceControl =  new FirstSamplePlugin();
    }
    else if ( in_rguidPluginID == s_guidSecondSamplePluginID )
    {
        pSourceControl =  new SecondSamplePlugin();
    }

    return pSourceControl;
}
Warning.gif
Warning: プラグイン GUID 値を変更し、他のプラグインとの ID の競合を避ける必要があります。

Visual Studio でプロジェクトを作成する時、関数名をプロジェクトの .def ファイルに追加することによって、これらの関数をエクスポートする必要があります。モジュール定義ファイルが存在しない場合は、これを作成する必要があります。

モジュール定義ファイルを作成するには、次の手順に従います：

  1. ツールバーの Add New Item ボタンをクリック。
  2. テンプレートリストで、Module-Definition File (.def) テンプレートを選択。

典型的なモジュール定義ファイルは次のようになります：

LIBRARY      "SamplePlugin"

EXPORTS
    AkSourceControlGetPluginIDList
    AkSourceControlGetPluginInfo
    AkSourceControlCreatePlugin

ソース管理インターフェースの導入

各 Wwise ソース管理プラグインは、適切に統合されるよう、特定のインターフェースが含んでいる必要があります。これについては、以下に要約されており、詳細については、このドキュメンテーションで後述されています。

AK::Wwise::ISourceControl

プラグインは、ソース管理操作を行うためにこのインターフェースを実装する必要があります。

このインターフェースに関する詳細は、ソース管理プラグインインターフェースの構築 をご覧ください。

AK::Wwise::ISourceControlUtilities

このインターフェースは、Wwise により実装され、その作成時にプラグインに与えられます。これは、プラグインにいくつかの有用なユーティリティ関数を公開します。

このインターフェースに関する詳細は、ソース管理ユーティリティインターフェースの使用 をご覧ください。

AK::Wwise::ISourceControlOperationProgress

このインターフェースは、Wwise により実装され、ISourceControlUtilities クラスを介してプラグインに与えられます。これは、単純なプログレスダイアログを管理するための関数を公開します。

このインターフェースに関する詳細は、 ソース管理操作プログレスインターフェースの実装 をご覧ください。

AK::Wwise::ISourceControlDialogBase

このインターフェースは、Wwise UI ルック アンド フィールを持つダイアログを作成するためにプラグインが実装する必要のあるインターフェースです。

このインターフェースに関する詳細は、ソース管理プラグインダイアログの定義 をご覧ください。

ソース管理プラグインインターフェースの構築

AK::Wwise::ISourceControl のメソッドを実装する時、Wwise における様々な状況に応じてプラグインの動作を定義します。メソッドにより、プラグインは次の状況に対処することができます：

  • プラグインインスタンスが初期化または終了された。
  • プラグインインスタンスが破棄された。
  • Wwise ユーザーが Project Settings ダイアログの "Config…" ボタンをクリックした。
  • Wwise が Project Explorer のアイコンをリフレッシュした。
  • File Manager のWork Units または Sources タブのファイルリストがリフレッシュされた。
  • ソース管理操作を含むコンテキストメニューが表示されている。
  • Wwise ユーザーが File Manager または Project Explorer のコンテキストメニューから操作を選択した。
  • ファイルが更新されている。
  • Wwise ユーザーがオーディオファイルをインポート、新しいワークユニットを作成、または、プロジェクトを保存した。

これらの状況の一部は、以下のセクションで説明されていますが、AKWwise::ISourceControl リファレンスを直接ご参照いただくと、実装する必要のあるインターフェースと関数についての完全な記述をご覧いただくことができます。

Tip.gif
Tip: このインターフェースの多くのメソッドは、戻り値の型として AK::Wwise::ISourceControl::OperationResult 列挙体を持ちます。OperationResult_Failed リザルトは、操作がグローバルに失敗した時、つまり、プラグインによって戻されるデータが Wwise によって考慮されないようにする場合にのみ使用されなければならないことに注意してください。このようなエラーには次のようなものがあります：
  • 接続の失敗。
  • プラグインの内部エラーが発生。

サンプルコード

このインターフェースの全てのメソッドを実装するには、AKWwise::ISourceControl から派生したクラスを作成する必要があります。このクラスは、プラグインの UI およびソース管理操作に関する全てを管理します。これらのメソッドが呼び出されるコンテキストは、コメント内で示されます。

#include <AK/Wwise/ISourceControl.h>

class SamplePlugin
    : public AK::Wwise::ISourceControl
{
public:
    SamplePlugin();
    virtual ~SamplePlugin();

    // ISourceControl implementation
    virtual void Init(AK::Wwise::ISourceControlUtilities* in_pUtilities ); // Initializing and Terminating the 
        // Plug-in Instance
    virtual void Term(); // Initializing and Terminating the Plug-in Instance
    virtual void Destroy(); // Destroying the Plug-in Instance

    virtual bool ShowConfigDlg(); // Plug-in configuration
    virtual void GetOperationList( OperationMenuType in_menuType, const StringList& in_rFilenameList, 
        OperationList& out_rOperationList ); // Contextual Menu
    virtual DWORD GetOperationEffect(
                DWORD in_dwOperationID ); // Wwise needs to know the effect of an operation
    virtual LPCWSTR GetOperationName(
        DWORD in_dwOperationID ); // Get operation name
    virtual AK::Wwise::ISourceControlUtilities::OperationResult GetFileStatus( 
        const StringList& in_rFilenameList, 
        FilenameToStatusMap& out_rFileStatusMap ); // File Manager Dialog
    virtual AK::Wwise::ISourceControlUtilities::OperationResult GetFileStatusIcons( 
        const StringList& in_rFilenameList, 
        FilenameToIconMap& out_rFileIconsMap ); // Project Explorer Icons Refresh
    virtual AK::Wwise::ISourceControlUtilities::OperationResult GetMissingFilesInDirectories( 
        const StringList& in_rDirectoryList, StringList& out_rFilenameList ); // File Manager Dialog
    virtual void DoOperation( DWORD in_dwOperationID, const StringList& in_rFilenameList ); // Execution of a 
        // Source Control Operation
    virtual AK::Wwise::ISourceControlUtilities::OperationResult PreCreateOrModify( 
        const StringList& in_rFilenameList, 
        bool& out_rContinue ); // Creation or Modification of Files in Wwise
    virtual AK::Wwise::ISourceControlUtilities::OperationResult PostCreateOrModify( 
        const StringList& in_rFilenameList, 
        bool& out_rContinue ); // Creation or Modification of Files in Wwise
    
// A static method to get the plug-in information class, refer to Source Control Plug-in Information Class 
// for more information about this method.
    static void GetPluginInfo( PluginInfo& out_rPluginInfo );

private:

    // Members
    AK::Wwise::ISourceControlUtilities* m_pSourceControlUtilities;
};
Caution.gif
Caution: Wwise とソース管理プラグインの間で交換される文字列パラメータとリザルトは Unicode である必要があります。

ソース管理プラグイン情報クラスの確立

Wwise は、プラグインに関する情報を必要とする場合、DLL からエクスポートされる AkSourceControlGetPluginInfo 関数を呼び出します。（詳細は、エクスポート関数の確立 をご参照ください。）AKWwise::ISourceControl::PluginInfo クラスは、以下のデータより構成されています：

  • ユーザーに表示されるプラグイン名
  • プラグインのバージョン
  • ワークユニットノード用ソース管理アイコンがProject Explorer で表示可能であることをWwiseに通知するブール値
  • プラグインの設定が可能であることを Wwise に通知するブール値
  • Update All 操作が利用可能であることを Wwise に通知するブール値
  • ユーザーに表示される Update All 操作の名前。
Tip.gif

Tip: プラグイン情報を取得する簡単な方法は、AkSourceControlGetPluginInfo (エクスポート関数の確立) に、AKWwise::ISourceControl インターフェースの実装内に作成された静的メソッドを呼び出させることです。

この静的メソッドの簡単な実装は次のようになります：

void SamplePlugin::GetPluginInfo( PluginInfo& out_rPluginInfo )
{
    // Plug-in name and version
    out_rPluginInfo.m_bstrName = ::SysAllocString( L"Sample Source Control Plug-in" );
    out_rPluginInfo.m_uiVersion = 1;

    // Function availability
    out_rPluginInfo.m_bShowConfigDlgAvailable = false;
    out_rPluginInfo.m_dwUpdateCommandID = AK::Wwise::SourceControlConstant::s_dwInvalidOperationID;// Replace with your ID
    out_rPluginInfo.m_dwCommitCommandID = AK::Wwise::SourceControlConstant::s_dwInvalidOperationID;// Replace with your ID
    out_rPluginInfo.m_bStatusIconAvailable = false;
}
Warning.gif
Warning: プラグイン名とUpdate All 操作名は、Wwise がこのメモリの削除を担うため、SysAllocString 関数を使用して割り当てる必要があります。

プラグインインターフェースの初期化と終了

プラグインインターフェースが作成されると、Wwise は AK::Wwise::ISourceControl::Init( ISourceControlUtilities* in_pUtilities ) メソッドを呼び出します。この関数のパラメータは、 Wwise の AK::Wwise::ISourceControlUtilities インターフェース実装へのポインタです。このポインタをプラグインクラスのメンバにコピーして、ダイアログを作成、プログレスダイアログを表示、メッセージボックスを表示、または、プラグイン構成をロードまたは保存したい場合があるかもしれません。このトピックに関する詳細は、ソース管理ユーティリティインターフェースの使用 をご参照ください。

AK::Wwise::ISourceControl::Init() の典型的な実装は次のとおりです：

void SamplePlugin::Init( ISourceControlUtilities* in_pUtilities )
{
    m_pSourceControlUtilities = in_pUtilities;

    // Load the plug-in configuration from the registry
}

プラグインインスタンスが破棄される前に、Wwise は AK::Wwise::ISourceControl::Term() メソッドを呼び出します。

AK::Wwise::ISourceControl::Term() の典型的な実装は次のとおりです：

void SamplePlugin::Term()
{
    // Save the plug-in configuration to the registry
    m_pSourceControlUtilities = NULL;
}

プラグイン構成のレジストリへのロード／保存に関する詳細は、ソース管理プラグインサンプルコード をご参照ください。

これらの関数がいつ呼び出されるかに関する詳細は、プラグインインスタンスの破棄 をご参照ください。

プラグインインスタンスの破棄

Wwise は、ソース管理プラグインのインスタンスを作成する必要がある場合、DLL (エクスポート関数の確立) に AkSourceControlCreatePlugin() 関数を呼び出し、新しいインスタンスを作成します。 この関数は、ソース管理プラグインにインターフェース返します。プラグインのインスタンスが不要になると、Wwise は、この特定のインスタンス上に AK::Wwise::ISourceControl::Destroy() メソッドを呼び出します。このメソッドは、オブジェクトが消費するメモリやその他のリソースを解放し、続いてオブジェクト自体を削除します。

インスタンスが、New 演算子で作成された場合、AKWwise::ISourceControl::Destroy() の典型的な実装は次のようになります：

void SamplePlugin::Destroy()
{
    delete this;
}

プラグインのインスタンスは、次のような場合に作成されます：

  • Wwise ユーザーが、Project Settingsダイアログのソース管理プラグインリストから選択し、変更を承諾。
  • Wwise ユーザーが、ソース管理プラグインを既に使用したプロジェクトをロード。

プラグインのインスタンスは、次のような場合に破棄されます：

  • Wwise ユーザーが、 Project Settings ダイアログから別のソース管理プラグインを選択し、変更を承諾。
  • プロジェクトが閉じられた。

ソース管理ユーティリティインターフェースの使用

このインターフェースは、プラグインインスタンスが初期化された場合にプラグインに与えられます ( プラグインインターフェースの初期化と終了 を参照)。 その関数は、プラグインの Wwise UI ルックアンドフィールでのダイアログ作成、メッセージボックス表示、プログレスダイアログ表示、構成のロードや保存を支援します。

このインターフェースは次のメソッドを公開します：

プログレスダイアログの表示

ソース管理操作を実行するとき、プログレスフィードバックメッセージにおけるプログレスダイアログ表示が有用です。これは、AKWwise::ISourceControlUtilities::GetProgressDialog() メソッドの呼び出しにより実行可能です。このメソッドは、AKWwise::ISourceControlOperationProgress インターフェースを返します。このインターフェースに関する詳細は、ソース管理操作プログレスインターフェースの実装 をご覧ください。

メッセージダイアログの表示

Wwise UI ルックアンドフィールでメッセージボックスを表示する簡単な方法は、AKWwise::ISourceControlUtilities::MessageBox() メソッドを呼び出すことです。標準 MessageBox Windows 関数呼び出しと同じように使用してください。プラグインに Wwise UI ルックアンドフィールを与えるためには、標準 MessageBox 呼び出しよりこちらのメソッドを使用してください。

ダイアログの表示

Wwise UI ルックアンドフィールを持つダイアログを作成するには、AKWwise::ISourceControlUtilities::CreateModalCustomDialog( ISourceControlDialogBase* in_pDialog ) メソッドを呼び出す必要があります。このメソッドは、AKWwise::ISourceControlDialogBase インターフェースを入力として受け入れること以外は、CDialogDoModal() メソッドと同じように機能します。詳細は、ソース管理プラグインダイアログの定義 をご参照ください。

プログレスダイアログの表示

AK::Wwise::ISourceControlUtilities は、レジストリにプラグイン構成を保存またはロードする簡単な方法を提供します。AKWwise::ISourceControlUtilities::GetRegistryPath() メソッドを呼び出すことにより、各プロジェクトやプラグインごとに異なるレジストリフォルダのパスを取得することができます。構成をロードまたは保存するには、プラグイン現行バージョンのサブフォルダを作成し、そこに全てのプラグインキーを作成する必要があります。AKWwise::ISourceControl::Init() メソッドにこの構成をロードし、これを AK::Wwise::ISourceControl::Term() メソッドに保存すると良いでしょう。

Warning.gif
Warning: このパスにアクセスするには、HKEY_CURRENT_USERレジストリキーを使用する必要があります。プロジェクトのレジストリフォルダはこのキーを使用して作成され、ソース管理プラグイン構成はユーザー非依存である必要があるためです。

ソース管理操作プログレスインターフェースの実装

AK::Wwise::ISourceControlOperationProgress インターフェースの実装には、初期化時にプラグインに与えられる AK::Wwise::ISourceControlUtilities インターフェースを介してアクセスすることができます。 前者インターフェースは次のメソッドを公開します：

プログレスダイアログの作成

プログレスダイアログを作成して公開するには、AKWwise::ISourceControlOperationProgress::ShowProgress() 非ブロッキングメソッドを使用します。ログメッセージリストにメッセージを追加するには、AKWwise::ISourceControlOperationProgress::AddLogMessage() メソッドを使用します。

Warning.gif
Warning: プログレスダイアログは、エスケープ文字（例： '\n' や '\t' 等）を考慮しません。 テキストは、1行ずつ追加する必要があり、タブはブランク（スペース）に置き換える必要があります。

OK ボタンの有効化

OK ボタンを有効化するには、AKWwise::ISourceControlOperationProgress::OperationCompleted() メソッドを呼び出します。このメソッドは、ユーザーが OK ボタンを押すまで戻りません。ユーザーが OK ボタンをを押すと、ダイアログが閉じられ破棄されます。

Cancel ボタンの有効化

ユーザーがCancel ボタンを押したかどうかを知るには、AKWwise::ISourceControlOperationProgress::IsCanceled() メソッドを呼び出します。この操作は、AKWwise::ISourceControlOperationProgress::Cancel() メソッドの呼び出しによりキャンセルすることもできます。

Note.gif
Note: AK::Wwise::ISourceControlOperationProgress::Cancel() メソッドの呼び出しにより、ダイアログをプログラム的にキャンセルした場合でも、ダイアログを閉じて破棄するには、AKWwise::ISourceControlOperationProgress::OperationCompleted() を呼び出す必要があります。

ソース管理アクションの実装

Wwise ユーザーのワークフローにソース管理プラグインを統合するには、次のような特定の機能を実装する必要があります。

プラグイン構成の有効化

Wwise ユーザーは、Project Settings ダイアログで Config… ボタンをクリックすることによりプラグインを構成することができます。このボタンは、AKWwise::ISourceControl::PluginInfo::m_bShowConfigDlgAvailable が True に設定されている場合にのみ有効化されます。このボタンをクリックすると、Wwise はAKWwise::ISourceControl::ShowConfigDlg() メソッドを呼び出します。この関数の戻り値はブール値です。値の意味は以下のとおりです：

  • True は構成の変更が受け入れられたことを示しているので、Project Explorer アイコンが更新されます。
  • False は構成の変更が拒否されたことを示しているので、Project Explorer アイコンは更新されません。

このメソッドの典型的な実装は次のとおりです：

bool SamplePlugin::ShowConfigDlg()
{
    DlgConfiguration configurationDialog();

    // return True if the user presses 'OK'
    return m_pSourceControlUtilities->CreateModalCustomDialog( &configurationDialog ) == IDOK;
}

このコードサンプルでは、DlgConfiguration クラスは AK::Wwise::ISourceControlDialogBase インターフェースの実装です。詳細は、ソース管理プラグインダイアログの定義 をご覧ください。

File Manager ダイアログの有効化

File Manager が更新されると、2つのメソッドが呼び出されます：

ファイルリストが移入されると、Wwise はディスク上にあるファイルを検索します。しかしながら、一部のソース管理システムでは、ファイルは削除された時点でディスクから削除されます。これにも関わらず、これらのファイルはサーバーにおける削除操作を確認するために識別される必要があります。この状態にあるファイルのリストを取得するために、Wwise は AK::Wwise::ISourceControl::GetMissingFilesInDirectories() メソッドを呼び出します。最初のパラメータは、Wwise がこのような欠損ファイルを探す際の検索先となるディレクトリのリストで、2番目のパラメータは、欠損ファイル名で上書きされる文字列のリストです。

Warning.gif
Warning: プラグインには、指定されたディレクトリのサブディレクトリにあるファイルを含めないでください。

Wwise の完全なファイルリストを取得したら、Status および Owner(s) のカラムをリフレッシュする必要があります。 これを実行するために、Wwise は AK::Wwise::ISourceControl::GetFileStatus() メソッドを呼び出します。プラグインは、各ファイルに対応するステータスや所有者を公開する必要があります。Wwise は関数の最初のパラメータにリストされたファイルのステータスを取得します。2つ目のパラメータは、Status および Owner(s) のカラムに公開されるテキストを含む結果のマップです。

Warning.gif
Warning: AK::Wwise::ISourceControl::FilenameToStatusMapItem の文字列メンバのメモリは Wwise によって削除されるので、このメモリは SysAllocString 関数を使用して割り当てられる必要があります。2つの文字列が同一メモリ空間を共有すると、Wwise はこれらの2つの文字列を別々に破棄しようとするため、これを避けてください。

コンテキストメニューへのプラグイン公開

Wwise がソース管理操作を含むコンテキストメニューを表示する際、特定のコンテキストで使用可能な全操作のリストを必要とします。このリストを取得するために、Wwise は AK::Wwise::ISourceControl::GetOperationList( OperationMenuType in_menuType, const StringList& in_rFilenameList, OperationList& out_rOperationList ) メソッドを呼び出します。最初のパラメータは、操作リストが表示されるコンテキストです。このコンテキストに応じて、一部のプラグインはユーザーを特定の操作に制限することができます。2つ目のパラメータは、ユーザーが選択したファイル名のリストです。これは、ファイルのステータスに応じて一部の操作を有効または無効にするために使用することができます。3つ目のパラメータは、現在のコンテキストで使用可能な操作のリストです。 この操作リストはプラグインによって埋められる必要があります。このリストに含まれている操作に関する情報は、コンテキストメニューを埋め、操作の ID でプラグインをコールバックするために使用されます。いずれの ID にも制限はありません。

Wwise は、LPCWSTR GetOperationName( DWORD in_dwOperationID ) 仮想メソッドを呼び出して、メニューやダイアログで表示する操作名を取得します。

Warning.gif
Warning: Wwise は操作名の文字列が占有しているメモリを削除しません。従って、プラグインインスタンスと同時に作成および破棄される静的文字列の作成をお勧めします。

コンテキストメニューにおけるソース管理操作の公開

Wwise ユーザーがコンテキストメニューから操作を選択すると、Wwise はまずはじめに AK::Wwise::ISourceControl::GetOperationEffect( DWORD in_dwOperationID ) メソッドを呼び出します。 パラメータは、この操作に対応する操作IDです。このメソッドの実装は、AKWwise::ISourceControl::OperationEffect 列挙体の単数または複数の値からなるマスクを返します。Wwise は戻り値を使用して、ソース管理操作を続行する前にプロジェクトを保存するようユーザーに依頼する必要があるかどうかを確認します。更新、名前の変更、リバート、削除などの操作はローカルファイルの内容を変更します。コミット、チェックインのような操作は、サーバー上のファイルの内容を変更します。

Warning.gif
Warning: ファイルに対する操作の影響に関する情報を返さないと、Wwise ユーザーのフラストレーションにつながる可能性があります。 ファイルがソース管理操作中にハードドライブ上で変更されると、Wwise はこの変更を検出し、ユーザーにプロジェクトをリロードするよう要求します。 ユーザーが保留中の変更を持ち（つまり、プロジェクトがダーティー）、リロードを要求された場合、この変更は失われます。ユーザーが、ダーティーであるファイルへの変更をリバートし、プロジェクトをリロードしないことを選択してから、変更を保存した場合、新たに更新されたファイルが上書きされる可能性があります。AKWwise::ISourceControl::GetOperationEffect は、返された情報を使用して、ユーザーに保存を強制することでこのような状況を避けます。

正常に最初のメソッドを呼び出した後、Wwise は AK::Wwise::ISourceControl::DoOperation( DWORD in_dwOperationID, const StringList& in_rFilenameList ) メソッドを呼び出します。最初のパラメータは、操作に対応する操作 IDです。2つ目のパラメータは、選択されたファイルのリストです。 このメソッドの実装は、AKWwise::ISourceControlOperationProgress インターフェースを使用して、プログレスダイアログを表示します。 詳細は ソース管理操作プログレスインターフェースの実装 をご覧ください。

Wwise への Project Explorer アイコンのリフレッシュ許可

Wwise は、次のような場合にアイコンをリフレッシュする必要があります：

  • ソース管理プラグインがロードされている。
  • ユーザーがプラグイン構成を受け入れ。
  • ユーザーが、Project Explorer コンテキストメニュー項目 "Refresh" または "Refresh All" をクリックして、アイコンを手動でリフレッシュ。
  • File Manager ダイアログが閉じられた。

AK::Wwise::ISourceControl::GetFileStatus() メソッドと同様のパターンを使用して、AKWwise::ISourceControl::GetFileStatusIcons( const StringList& in_rFilenameList, FilenameToIconMap& out_rFileIconsMap ) は、リスト内のファイルのアイコンおよびツールチップのテキストを含むマップを返す必要があります。最初のパラメータは、Wwise がアイコンマップを有する必要のあるファイル名のリストです。2つ目のパラメータは、以下のコンポーネントを含む結果のマップです：

  • ワークユニットのオリジナルアイコンのオーバーレイとして表示されるアイコン。
  • 特定のアイコン上にマウスを移動すると表示されるツールチップテキスト。
Warning.gif
Warning: AK::Wwise::ISourceControl::FilenameToIconMapItem の文字列メンバのメモリは Wwise によって削除されるので、このメモリは SysAllocString 関数を使用して割り当てられる必要があります。2つの文字列が同一メモリ空間を共有すると、Wwise はこれらの2つの文字列を別々に破棄しようとするため、これを避けてください。

マップに含まれているアイコンは任意のサイズにすることができますが、15x15 ピクセルのフォーマットにリサイズされます。 アイコンに関連する関数は、AKWwise::ISourceControl::PluginInfo::m_bStatusIconAvailable が Trueに設定されている場合のみ呼び出されます。

Tip.gif
Tip: ご使用いただけるアイコンのセットは、この SDK にインストールされています。

Wwise におけるファイルの作成と変更

Wwise ユーザーが以下を実行すると、ファイルの作成や変更が発生します：

  • 新しいワークユニットの作成。
  • オーディオソースのインポート。
  • プロジェクトの保存。
  • 外部エディタによるオーディオソースの編集。

これらのいずれかの状況が発生すると、Wwise は AK::Wwise::ISourceControl::PreCreateOrModify( const StringList& in_rFilenameList, CreateOrModifyOperation in_eOperation, bool& out_rContinue ) メソッドおよび AK::Wwise::ISourceControl::PostCreateOrModify( const StringList& in_rFilenameList, CreateOrModifyOperation in_eOperation, bool& out_rContinue ) メソッドを呼び出します。最初のパラメータは、作成または変更されるべきファイル名リストです。2つ目のパラメータは、実行される操作を定義するフラグです。リストされている任意のファイルに対していずれかの操作を実行することができるので、ビットごとの AND 演算子を使用して、2つ目のパラメータと事前定義されたフラグを比較する必要があります。例えば、一部のファイルが作成されたかどうかを知るには、次を実行してください：

if ( in_eOperation & CreateOrModifyOperation_Create )
{
    // Do operations
}

AK::Wwise::ISourceControl::PreCreateOrModify() 関数および AK::Wwise::ISourceControl::PostCreateOrModify() 関数の3つ目のパラメータはプラグインにより設定され、Wwise に現行操作を続行するか停止するかを通知します。このパラメータは、主に AK::Wwise::ISourceControl::PreCreateOrModify() メソッドへの呼び出しによって使用されます。

Tip.gif
Tip: これらの2つのメソッドを、ご使用のソース管理システムに固有の操作を実行するために使用することをお勧めします。例えば、AKWwise::ISourceControl::PreCreateOrModify() メソッドは、Perforce のチェックアウト操作を実行するために、また、AKWwise::ISourceControl::PostCreateOrModify() メソッドは、まだサーバー上にないファイルを追加するために使用することができます。最初のメソッドは、常にファイル作成または変更の前に呼び出され、2つ目のメソッドは、常にこのような操作の後に呼び出されます。この機能は、プラグインのセキュリティ層を実装するために使用可能です。

ソース管理プラグインダイアログの定義

DLL にダイアログが含まれている場合、これらのダイアログが Wwise UI のルックアンドフィールを持つようにしてください。これを実行するには、以下の手順に従ってください：

ダイアログリソースの作成

標準的な Windows コントロールと Wwise に固有のコントロールを作成することができます。

標準コントロール

静的コントロール、編集コントロール、チェックボックス、プッシュボタン、ラジオボタンなどの標準コントロールとグループコントロールを、Toolbox の Dialog Editor セクションにある対応ツールを使用して、Microsoft Development Environment Dialog Editor に直接追加することができます。これらのコントロールは、自動的に Wwise によってサブクラス化され、アプリケーションの別の場所にある同様のコントロールと同じ外観を持つようになります。

Note.gif
Note: ドロップボックス／コンボボックス コントロールは、自動的にサブクラス化されません。ダイアログにドロップダウンコントロールが必要な場合は、代わりに Combo カスタムを使用してください。詳細は、Wwise コントロールをご覧ください。

Wwise コントロール

Wwise ダイアログコントロール（Captions や ComboBox など）をダイアログに統合するには、特別にコード化されたキャプションテキストを持つ静的テキストコントロール プレースホルダを使用します。このテキストは、次の形式を持っている必要があります：

Class=[Classname];

ここで Classname は次のいずれかです：

  • Caption: 読み取り専用テキストの表示
    リソースの静的コントロールは、厳密に 13 ユニットの高さである必要があり、収容可能性のある最長のテキストを収容できる幅でなければなりません。キャプションのテキストを変更するには、次の標準 Windows 関数を使用すします：
    • SetWindowText
    • GetWindowText
  • Combo: ドロップダウンリスト
    リソースの静的コントロールは、厳密に 13 ユニットの高さである必要があり、収容可能性のある最長のテキストを収容できる幅でなければなりません。コンボボックスまたはいずれかのセットを移入または現在の選択状態を取得するには、次のような標準 Windows メッセージマクロを使用します：
    • ComboBox_InsertString
    • ComboBox_GetCurSel
    • ComboBox_SetCurSel
Tip.gif
Tip: ダイアログコントロールのレイアウト表示を簡単にするには、 Microsoft Development Environment Dialog Editor 内の静的プレースホルダのプロパティで Border を True に設定してください。

ダイアログの有効化

Wwise がダイアログを表示できるようにするには、AKWwise::ISourceControlDialogBase インターフェースを実装する必要があります。 このインターフェースは次のメソッドを公開します：

Wwise は、リソースを見つけることのできるコンテキストを認識している必要があります。ダイアログを作成する前に、Wwise は AK::Wwise::ISourceControlDialogBase::GetResourceHandle() メソッドを呼び出します。このメソッドの典型的な実装は次のとおりです：

HINSTANCE DlgSimple::GetResourceHandle() const
{
    AFX_MANAGE_STATE( ::AfxGetStaticModuleState() );
    return ::AfxGetResourceHandle();
}

Wwise は、ダイアログを作成するために、リソース内のダイアログのIDを必要とします。これを取得するために、Wwise は AK::Wwise::ISourceControlDialogBase::GetDialog() メソッドを呼び出します。このメソッドの典型的な実装は次のとおりです：

void DlgSimple::GetDialog( UINT & out_uiDialogID ) const
{
    out_uiDialogID = IDD_SIMPLEDIALOGID;
}

ダイアログのタイトルバーに、"?" が表示されるかどうかを知るために、Wwise は AK::Wwise::ISourceControlDialogBase::HasHelp() を呼び出します。 ダイアログに関連する Help セクションがある場合、プラグインは True を返す必要があります。この場合、"?" アイコンが表示されます。

bool DlgSimple::HasHelp() const
{
    return true;
}

Wwise ユーザーがダイアログの "?" ボタンをクリックすると、Wwise は AK::Wwise::ISourceControlDialogBase::Help() メソッドを呼び出します。プラグインは、Help リクエストを処理する場合には True を返し、何も行わない場合には False を返す必要があります。このメソッドの実装例は、次のとおりです：

bool DlgSimple::Help( HWND in_hWnd ) const
{
    AFX_MANAGE_STATE( ::AfxGetStaticModuleState() ) ;

    // Note: Do NOT call AfxGetApp()->HtmlHelp() as it will launch the Help
    // window from the wrong parent window which will make floating views
    // behave unexpectedly.
    ::HtmlHelp( NULL, AfxGetApp()->m_pszHelpFilePath, HH_HELP_CONTEXT, ONLINEHELP::Simple_Dialog );

    return true;
}
Caution.gif
Caution: Help() メソッドは、AfxGetApp()->HtmlHelp() を呼び出すべきではありません。とうのも、これにより間違った親ウィンドウから Help ウィンドウを起動してフローティングビューが予期しない動作を起こす可能性があるからです。 代わりに、上の例で示されているように、HtmlHelp() を NULL ウィンドウハンドルで使用するようにしてください。

ダイアログは、Windows メッセージを管理するためにMFC メソッドを使用することができません。代わりに、ダイアログが Windows メッセージを受け取るたびに、AKWwise::ISourceControlDialogBase::WindowProc() が呼び出されます。このメソッドの実装例は次のとおりです：

bool DlgConfiguration::WindowProc( HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, 
    LRESULT & out_lResult )
{

    if ( in_message == WM_INITDIALOG )
    {
        // Initialize the dialog
    }

    // For example: Catch window command actions (only for the main dialog) to enable/disable controls
    else if ( in_message == WM_COMMAND )
    {
        // Notification code
        switch ( HIWORD( in_wParam ) )
        {
        case BN_CLICKED:
            // Check which button was clicked
            switch ( LOWORD( in_wParam ) )
            {
            case IDOK:
                // The user pressed the 'Ok' button
                break;
            }           
        } // End switch hi word (notification code)

    } // End command window event

    // Return False to let the parent window deal with the message. Return True
    // for messages you don't want the parent window to handle.

    return false;
}

このメソッドの戻り値の意味は、次のとおりです：

  • Falseは、メッセージがオブジェクトの親クラスに伝播されることを示します。これは、一般的に返される値です。
  • True は、メッセージがオブジェクトの親クラスに伝播されないことを示します。親がメッセージに反応しないようにしたい場合には、この値を返してください。例えば、 IDOK ボタンメッセージを受信した場合などには、通常、親はダイアログを閉じます。特定の状況において、一部の情報が正常に完了していない場合には、ダイアログを開かせることをお勧めします。

ダイアログを手動で閉じるには、Windows の PostMessage() 関数を使用する必要があります。この関数への典型的な呼び出しは、次のようになります：

PostMessage( in_hWnd, WM_CLOSE, 0, 0 );

ダイアログの表示

ダイアログを表示するには、対応する AK::Wwise::ISourceControlDialogBase 実装のインスタンスを作成する必要があります。AKWwise::ISourceControlUtilities::CreateModalCustomDialog() メソッドを使用して、ダイアログはモーダルダイアログのように表示されます。以下は、ダイアログ作成および表示方法を示す例です：

bool SamplePlugin::ShowConfigDlg()
{
    DlgConfiguration configurationDialog( m_pSourceControlUtilities );

    // return true if the user presses 'OK'
    return m_pSourceControlUtilities->CreateModalCustomDialog( &configurationDialog ) == IDOK;
}

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう