Node3D プラグインの例

この例では、カスタム3Dノードを作成する方法と、それらのノードを Kanzi Studio で使用する方法を示します。

例の入手

この例を入手するには、Kanzi Studio Quick Start ウィンドウで Examples をクリックします。Node3D_plugin の例の横にある ダウンロード をクリックします。

Kanzi Studio は、この例を <KanziWorkspace>/Examples/Node3D_plugin ディレクトリにダウンロードします。

例の内容

この例には以下が含まれています。

  • カスタムノードを定義する Kanzi Engine プラグイン。

  • Kanzi Studio プロジェクトは、Kanzi Engine プラグインを使用して、Kanzi Studio Preview にカスタムノードで定義された動作を適用します。

Kanzi Engine プラグインの作成方法を学ぶには、Kanzi Engine プラグインの作成 を参照してください。

カスタムノードの作成

この例には、次のカスタムノードがあります。

  • Knob は、ユーザー入力に反応して、ノブの現在の回転角度に関するメッセージを送信します。ノブは、ユーザー入力から検出されたパンジェスチャーに基づいて独自のメッセージを生成します。ノブは、Kanzi Studio でノブにインターセプトされるこれらのメッセージタイプを生成します。

    • ノブの回転は、引数をそのZ回転属性に直接渡すことによって、ノブの外部ビジュアライゼーションに転送されます。

    • 離散レベルの更新は、アプリケーションイベント（メッセージも含む）を生成することによって処理され、これらはスピナーノードに渡されます。

  • Spinner は、メッセージに反応して Text Block ノードの Text プロパティを更新し、ノブからの値を表示します。スピナーは外部からのメッセージを受け取り、自身の定義された動作に基づいてそれらのメッセージに反応します。

Kanzi Studio は、プラグイン DLL からカスタムノードで使用されるメッセージとプロパティタイプに関する情報を読み取ります。

Kanzi Engine は、プラグインからこのシグネチャを持つ関数を呼び出すことによってプラグインを登録します。

extern "C"
{
    __declspec(dllexport) Module* createModule(uint32_t kanziVersionMajor, uint32_t kanziVersionMinor);
}

ノブノードとスピナーノードは、あなたが作成するモジュールで定義され、createModule() 関数が返す Module::getMetaclassesOverride 関数に登録されます。

スピナーノードを登録するには、スピナーがメタクラスを含んでいる必要があります。metaclass.hpp::KZ_METACLASS_BEGIN を使用することで、カスタムノードを定義し、そこで次のように宣言します。

  • 基底クラス (Node3D)

  • ユニークID ("Spinner")

  • 使用するメッセージ (SpinnerUpdateLevelMessage)

  • 使用するプロパティタイプ (TextBlockProperty)

spinner.hpp ファイル内のスピナーノードのメタデータ宣言は次のようになります。

KZ_METACLASS_BEGIN(Spinner, Node3D, "Spinner")
    KZ_METACLASS_MESSAGE_TYPE(SpinnerUpdateLevelMessage)
    KZ_METACLASS_PROPERTY_TYPE(TextBlockProperty)
KZ_METACLASS_END()

この例では、spinner.cpp ファイル内で、スピナーは SpinnerUpdateLevelMessageArguments を使用することを指定することによって、メッセージタイプ SpinnerUpdateLevelMessage を作成します。

MessageType<Spinner::SpinnerUpdateLevelMessageArguments> Spinner::SpinnerUpdateLevelMessage(
    kzMakeFixedString("Message.Spinner.UpdateLevel"),
    KZ_DECLARE_EDITOR_METADATA(
        // Set the name of the message the way it is shown in Kanzi Studio.
        metadata.displayName = "Update Level";
        // Set the tooltip for the message.
        metadata.tooltip = "Updates the Spinner level and outputs the level to a text block.";
        // Do not show the message as a trigger.
        // Do this when you want to show a message in Kanzi Studio as an action.
        metadata.listenable = "False";
    ));

SpinnerUpdateLevelMessage のメッセージ引数を登録するには、SpinnerUpdateLevelMessageArguments にメッセージ引数を定義するメタクラスが含まれている必要があります。metaclass.hpp::KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN を使用することで、カスタムメッセージの引数を定義し、次のように宣言します。

  • 基底クラス (MessageArguments)

  • ユニークID ("Spinner Update Level Message Arguments")

  • プロパティタイプ (SpinnerLevelAlterationProperty)

KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(SpinnerUpdateLevelMessageArguments, MessageArguments, "Spinner Update Level Message Arguments")
    KZ_METACLASS_PROPERTY_TYPE(SpinnerLevelAlterationProperty)
KZ_METACLASS_END()

カスタム3Dノードのデバッグビジュアライゼーションを作成する

カスタム3Dノードのために、Preview が Analyze モードにあるときに Kanzi Studio で表示されるデバッグビジュアライゼーションを作成できます。これらのビジュアライゼーションを使用して、プラグインの開発中に役立つ情報をレンダリングしてください。

Node3Dプラグインの例は、Knobノードのデバッグビジュアライゼーションを作成します。

  1. knob.cpp ファイルでは、drawKnobDebug 関数がデバッグビジュアライゼーションを描画します。これは、ノブの中心から異なる方向に伸びる4本の線で構成されています。

    // Renders a debug visualization of the Knob.
void drawKnobDebug(Renderer3D& renderer, NodeSharedPtr object)
{
    // This example of a debug visualization draws four green lines that extend from the
    // origin of the Knob node to different directions. When you rotate the Knob, the
    // visualization rotates.

    const ColorRGBA color(0.0f, 1.0f, 0.0f);

    auto knobNode = dynamic_pointer_cast<Knob>(object);
    if (!knobNode)
    {
        return;
    }

    MaterialSharedPtr material = Material::acquireDebugMaterialSolid(*renderer.getResourceManager());
    if (!renderer.applyColorMaterial(knobNode.get(), *material, color))
    {
        return;
    }

    Matrix4x4 worldTransformation = knobNode->getFinalTransformation();

    span<float> floatBuffer = renderer.getFloatBuffer();
    const float radius = 5.0f;
    const unsigned int lineCount = 4;

    kzAssert(!floatBuffer.empty());
    float* dataIt = floatBuffer.data();

    // Get the rotation angle of the knob.
    float rotation = knobNode->getRotation();
    auto rotationTransform = Matrix4x4::createZRotationInRadians(rotation);

    // Knob visualization.
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(0.1f, 0.0f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(radius, 0.0f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(-0.1f, 0.0f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(-radius, 0.0f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(0.0f, 0.1f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(0.0f, radius, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(0.0f, -0.1f, 0.0f), dataIt);
    Renderer3D::addVertexToFloatArray(rotationTransform * Vector3(0.0f, -radius, 0.0f), dataIt);

    renderer.drawLineList(floatBuffer.data(), lineCount, worldTransformation, *material);
}

  2. node3d_plugin_module.cpp ファイルでは、Module::registerDebugRenderingFunctions 関数がプラグインモジュールのデバッグレンダリング関数を登録します。DebugRenderRegistry::addMapping 関数を使用して、Knob クラスを drawKnobDebug 関数に関連付け、ビジュアライゼーションを描画します。

    // Registers the debug visualization function.
void Node3DPluginModule::registerDebugRenderingFunctions(DebugRenderRegistry& registry)
{
    // Add a mapping from the Knob class to the function that you use to render a
    // debug visualization of the knob and its rotation.
    registry.addMapping(Knob::getStaticMetaclass(), drawKnobDebug);
}

Kanzi Studio でデバッグビジュアライゼーションを表示するには、Preview で 解析オフ をクリックして Analyze モードに入り、アナライズオン を右クリックして Debug objects を選択します。Preview でノブを回すと、ビジュアライゼーションが回転します。

../../_images/preview-debug-visualization.png

例を実行する

例を実行するには、

  1. Kanzi Studio で、File > Open Kanzi Command Prompt を選択します。

    Kanzi Command Prompt は、Kanzi 環境変数が設定された Windows コマンドプロンプトを開き、Kanzi のバージョンに対して Kanzi Command Prompt を開きます。

    Kanzi Command Prompt を使用して、絶対パスや環境変数を設定せずに、Gradle、SCons、CMake などの Kanzi ユーティリティおよびビルドツールにアクセスします。

    ../../_images/open-kanzi-command-prompt.png

    ヒント

    Kanzi Command Prompt は、Rightware ディレクトリの Windows スタートメニューで見つけることができます。

    Kanzi のバージョンが複数インストールされている場合は、そのコマンドプロンプトで作業したい Kanzi のバージョンに対応する Kanzi Command Prompt を起動するようにしてください。

  2. <KanziWorkspace>/Examples/Node3D_plugin/Application ディレクトリ内の Kanzi Command Prompt で、サンプルアプリケーション用の Visual Studio ソリューションを生成するスクリプトを実行します。

    たとえば、Visual Studio 2019 を使用している場合は、次のコマンドを実行します。

    generate_cmake_vs2019_solution.bat

    このスクリプトは、ディレクトリ <KanziWorkspace>/Examples/Node3D_plugin/Application/build_vs2019 内のアプリケーション用のVisual Studioソリューションを生成します。

  3. Visual Studioで <KanziWorkspace>/Examples/Node3D_plugin/Application/build_vs<Version>/Node3D_plugin.sln Visual Studioソリューションを開きます。

  4. Visual Studioのソリューションエクスプローラーで、Node3D_plugin_executable プロジェクトを右クリックし、Set as StartUp Project を選択します。

  5. 使用したいソリューション構成を選択し、アプリケーションを実行します。

    開発中は、Debug 構成を選択します。製品版を作成する準備ができたら、Release 構成を選択します。

    ../../_images/debug-configuration.png

関連項目

Kanzi Engine プラグイン

Kanzi Engine プラグインの作成

Kanzi Engine の機能を拡張する

Kanzi Studio で Kanzi Engine プラグインのカスタムタイプを表示するためのリファレンス