Kanzi 3.6 マイグレーションガイド

このマイグレーションガイドを使用して、Kanzi アプリケーションを Kanzi 3.5 から Kanzi 3.6 に更新してください。

ヘッダーのディレクトリ構造

Kanzi 3.6では、<KanziWorkspace>/Engine ディレクトリ構造に変更が導入されました。Kanzi アプリケーションを Kanzi 3.5から Kanzi 3.6に移行するには、アプリケーションコード内のインクルードパスを更新してください。

例えば、アプリケーションが kzs_file_base.h、v8_module.hpp、gl_graphics_output.hpp ヘッダーを使用している場合、変更します。

#include <system/file/kzs_file_base.h>
#include <kanzi/v8_module.hpp>
#include <kanzi/graphics_backend/gl_graphics_output.hpp>

終点

#include <kanzi/core/legacy/file/kzs_file_base.hpp>
#include <kanzi/js/module.hpp>
#include <kanzi/core.ui/platform/graphics_backend/gl/gl_graphics_output.hpp>

これらのテーブルは、Kanzi 3.5と3.6のディレクトリ構造の違いを示しています。

Kanzi 3.5

ディスクリプション (Description)

Engine/include/application_framework

プラットフォーム固有のアプリケーションヘッダーを含みます。

Engine/include/core

ユーティリティ、メモリ管理、およびデータ構造のヘッダを含みます。

Engine/include/kanzi_components

Kanzi UIコンポーネントのヘッダーを含みます。

Engine/include/kanzi_v8

JavaScriptサポートのヘッダーを含みます。

Engine/include/system

ネイティブプラットフォーム抽象化とグラフィックスシステム初期化ヘッダーを含みます。

Engine/include/user

アプリケーションロジックとサブシステムのヘッダーを含みます。

Kanzi 3.6

ディスクリプション (Description)

Engine/include/kanzi/core

これらの Kanzi 3.5 ディレクトリの非グラフィック部分の内容を結合します。

  • include/core

  • Engine/include/system

  • Engine/include/user

Engine/include/kanzi/core/legacy

これらの Kanzi 3.5ディレクトリの内容が含まれており、Kanzi の今後のバージョンで削除される予定です。

  • Engine/include/system

  • Engine/include/core

Engine/include/kanzi/core.ui

UI機能の基本サブシステムを含んでおり、すべてのUIコントロールとUIコンポーネントの基盤を形成します。例えば、これには入力、レンダリング、およびレイアウト機能が含まれます。これらの Kanzi 3.5ディレクトリのグラフィック部分の内容を組み合わせます。

  • include/core

  • Engine/include/system

  • Engine/include/user

Engine/include/kanzi/js

JavaScriptサポートのためのヘッダーを含みます。Kanzi 3.5 ディレクトリ Engine/include/kanzi_v8 を置き換えます。

Engine/include/kanzi/ui

Kanzi UIコンポーネントのヘッダーを含みます。Kanzi 3.5 ディレクトリ Engine/include/kanzi_components を置き換えます。

プリプロセッサーデファイン (Preprocessor Defines)

Kanzi アプリケーションをビルドするために独自の makefile やビルドスクリプトを作成した場合、Kanzi 3.6 を使用して Kanzi アプリケーションをビルドするには、これらのファイルを更新して KANZI_FEATURE_3D プリプロセッサ定義を含めてください。

ロギング

Kanzi 3.6では、ロギングシステムに変更が導入されました。ロギングシステムには新しい型安全なフォーマット構文が追加され、メッセージの分類とフィルタリングを実装するためにログレベルとログカテゴリが導入されました。ログカテゴリを使用すると、各カテゴリのメッセージをフィルタリングし、コンパイル時にメッセージをフィルタリングすることができます。

ログヘッダーは現在、ディレクトリ Engine/include/kanzi/core/log にあります。ログにメッセージを書き込むには、ログマクロを使用し、ログメッセージのログレベルとカテゴリを設定してください。Kanzi 3.6では、アプリケーションウィンドウにログメッセージを表示することはできず、デバッグコンソールにのみ表示されます。また、アプリケーション設定機能 logVisualizationEnabled() は利用できなくなりました。

この例は、Kanzi 3.5から Kanzi 3.6への一般的なロギング機能の移行を示しています。

// Define a new log category in a header file.
// For example, to define a log category called Texture.
#define TEXTURE_LOG_CATEGORY KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "Texture")

// Error log.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_INFO, "Texture loaded.");
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture loaded."));

// Formatted text.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Texture size %4dx%4d", 400, 600));
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture size {:4}x{:4}.", 400, 600));

// Assign test log message to the Generic log category.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_WARNING, "Test warning message.");
// In Kanzi 3.6
kzLogWarning(KZ_LOG_CATEGORY_GENERIC, ("Test warning message."));

// In Kanzi 3.6 the type of the argument is deduced at compile-time so that you do not have to set it.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Test different formatting: %+04d %#x %12.15f %-+12.15g", 1, 2, 0.1, 0.5));
// In Kanzi 3.6
kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Test different formatting: {:+04} {:#x} {:12.15} {:<+12.15} ", 1, 2, 0.1, 0.5));

log.hpp を参照してください。

レンダリング

Kanzi 3.6 はレンダリングに変更を導入します。

  • RenderPass クラスのクラス階層が変更されました。

    • Kanzi 3.5 RenderPass クラスは、Kanzi 3.6 LegacyRenderPass で呼び出されます。

    • Kanzi 3.5 Composer クラスは、Kanzi 3.6 RenderPass で呼び出されます。独自のレンダーパスを定義する場合は、RenderPass クラスから派生する必要があります。

  • 独自のレンダーパスを作成する場合、RenderPass::renderOverride() 関数は Kanzi 3.5 仮想関数 applyOverride() に置き換えられました。

Kanzi Engine プラグイン

プロパティタイプの定義

Kanzi 3.6では、Kanzi Engine プラグインでプロパティタイプを定義するためのフラグがリネームされました。

Kanzi 3.5

Kanzi 3.6

KZU_PROPERTY_TYPE_CHANGE_FLAG_FINAL_TRANSFORMATION

PropertyTypeChangeFlagFinalTransformation

KZU_PROPERTY_TYPE_CHANGE_FLAG_MEASURE

PropertyTypeChangeFlagMeasure

KZU_PROPERTY_TYPE_CHANGE_FLAG_PARENT_MEASURE

PropertyTypeChangeFlagParentMeasure

KZU_PROPERTY_TYPE_CHANGE_FLAG_ARRANGE

PropertyTypeChangeFlagArrange

KZU_PROPERTY_TYPE_CHANGE_FLAG_RENDER

PropertyTypeChangeFlagRender

KZU_PROPERTY_TYPE_CHANGE_FLAG_DRAW

PropertyTypeChangeFlagDraw

KZU_PROPERTY_TYPE_CHANGE_FLAG_CONSTRAINT

PropertyTypeChangeFlagConstraint

エディターメタデータ

Kanzi 3.6では、Kanzi Engine プラグインで作成するコンポーネントのエディターメタデータの宣言方法に変更が導入されています。

例えば、Kanzi 3.5 で、カスタムノード VideoView2D のためにカスタムプロパティタイプ VideoFileNameProperty を作成するには、使用しました。

PropertyType<string> VideoView2D::VideoFileNameProperty(KZ_PROPERTY_TYPE_EDITOR_INFO([]() -> kanzi::PropertyTypeEditorInfo::AttributeDictionary { kanzi::PropertyTypeEditorInfo::AttributeDictionary dict;
    dict["DisplayName"] = "Video Filename";
    dict["Tooltip"] = "Video file to be played";
    dict["Host"] = "VideoView2D:freq";
    return dict; }()), kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false);

Kanzi 3.6で、同じカスタムプロパティタイプを作成するには、使用します。

PropertyType<string> VideoView2D::VideoFileNameProperty(kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false,
                                                        KZ_DECLARE_EDITOR_METADATA
                                                        (
                                                            metadata.displayName = "Video Filename";
                                                            metadata.tooltip = "Video file to be played";
                                                            metadata.host = "VideoView2D:freq";
                                                        ));

この表は、Kanzi 3.5と3.6の間で Kanzi Engine プラグインエディタメタデータの宣言の違いを示しています。

Kanzi 3.5

Kanzi 3.6

dict["Category"]

metadata.category

dict["DefaultValue"]

metadata["DefaultValue"]

dict["DisplayName"]

metadata.displayName

dict["Editor"]

metadata.editor

dict["Host"]

metadata.host

dict["LowerBound"]

metadata["LowerBound"]

dict["Step"]

metadata["Step"]

dict["UpperBound"]

metadata["UpperBound"]

dict["Tooltip"]

metadata.tooltip

dict["Type"] = "Enum";dict["Options"] = "string1|int1;string2|int2;...;stringN|intN";

metadata.valueProvider = "Enum:string1|int1;string2|int2;...;stringN|intN";

dict["Type"] = "ProjectObject";dict["TargetType"] = "value";

metadata.valueProvider = "ProjectObject:value";

dict["Type"] = "PropertyType";

metadata.valueProvider = "PropertyType";

dict["Type"] = "StringList";

metadata.valueProvider = "StringList";

Kanzi 3.5で利用可能なすべてのフィールドで、ここに記載されていないものは、プロパティタイプ自体のメタデータ標準フィールドから取得されます。

Kanzi Engine の機能を拡張する と Kanzi Studio で Kanzi Engine プラグインのカスタムタイプを表示するためのリファレンス を参照してください。

トリガーとアクション

Kanzi 3.6では、トリガーが Trigger クラスで定義され、アニメーションプレーヤーが AnimationPlayer クラスで定義されています。両方のクラスは NodeComponent クラスから派生しています。Kanzi 3.5では、AnimationPlayer クラスが Trigger クラスから派生しています。

Preload Resources アクションと On Preloading of Resources Completed トリガー

Preload Resources アクションと On Preloading of Resources Completed トリガーは利用できなくなりました。Prefab View ノードを使用して、実行時にリソースを非同期でロードしてください。ノードプレハブの使用 を参照してください。

アプリケーションの実行中にリソースを非同期でロードするために、Kanzi Engine API を使用して、ResourceManager::acquireResourcesAsync と Node::acquireResourceAsync を使用します。Kanzi Engine API では、collect_resource_urls.hpp ファイルを参照してください。

Kanzi Studio の以前のバージョンで作成されたプロジェクトを開き、Preload Resources アクションまたは On Preloading of Resources Completed トリガーが含まれている場合、Kanzi Studio 3.6はこれらのアクションとトリガーを削除します。

Play Animation アクション

Play Animation アクションは利用できなくなりました。代わりにアニメーションプレーヤーとアクションを使用してください。Kanzi 3.5 移行ガイド を参照してください。

プロパティ名前空間

Kanzi Studio 3.6 フォルダ内の Library > Property Types では、プロパティタイプの名前空間階層が表示されます。

Kanzi Studio の以前のバージョンで作成されたプロジェクトを開き、Library > Property Types にフォルダが含まれている場合、Kanzi Studio 3.6 はこれらのフォルダを削除し、プロパティタイプを Library > Property Types ルートに配置します。

メッシュの属性の編集

Kanzi Studio プロジェクトを開くと、Kanzi Studio はプロジェクトに含まれるメッシュのメッシュデータを変更します。

  • Kanzi Studio は、Kanzi Studio 3.5のメッシュ属性マッピングを Kanzi Studio 3.6で使用されるスタイルに変換します。3.5スタイルのマッピングには、メッシュとシェーダーの属性名のペアがあります。これに加えて、3.6スタイルにはセマンティックとセマンティックインデックスフィールドが含まれています。コンバーターは、セマンティックとセマンティックインデックスフィールドに一致するシェーダー属性にメッシュ属性をマッピングしようとします。Kanzi Studio は、この変換中に遭遇した警告を KanziStudio.log に書き込みます。

  • メッシュ属性には、エクスポートセマンティクスとエクスポートセマンティックインデックスが含まれるようになりました。この変換中にエクスポート属性が設定されていない場合、Kanzi Studio はインポートセマンティクスからエクスポートセマンティクスをコピーし、セマンティックインデックスを配置します。

メッシュ属性マッピングに対する Kanzi Studio の変更の完全なリストを確認するには、Kanzi Studio の以前のバージョンで作成されたプロジェクトを開いた後、Kanzi Studio ログファイルを開いてください。Kanzi Studio ログは %USERPROFILE%\AppData\Local\Temp\KanziStudioLogs\KanziStudio.log にあります。参照してください。

Mesh Attributes Editor を使用してメッシュの属性を編集できるようになりました。Mesh Attributes Editor は、Kanzi の以前のバージョンで使用されていたマッピングメッシュ属性を置き換えます。メッシュの最適化 を参照してください。

../../_images/mesh-attributes-editor.png

アプリケーションアイドル状態

Kanzi は、変更がない場合に検出してレンダリングを停止するようになりました。Kanzi アプリケーションで、Kanzi Engine API を使用して宣言したカスタムプロパティタイプをシェーダーで使用している場合、または Kanzi Studio でそれらを作成した場合は、これらのプロパティタイプに Affect Rendering プロパティが有効になっていることを確認してください。アプリケーションアイドル状態 を参照してください。

APIのリネーム

  • getProperty 関数が変更されました

    bool getProperty(PropertyType propertyType, DataType& value)

    終点

    optional<DataType> getOptionalProperty(PropertyType propertyType)

  • setTrajectoryResourceID 関数が変更されました

    setTrajectoryResourceID(ResourceID("MyTrajectory"));

    終点

    setTrajectory(trajectory);

  • TrajectoryListBox3D::setLoopAlongY を削除し、TrajectoryListBox3D::setLoopAlongX を TrajectoryListBox3D::setLooping から変更しました。

  • KzcVolume を C++ に変換し、Box に名前を変更しました。

  • クラス Shader は ShaderProgram に名前が変更されました。

  • VertexAttribute クラスは、VertexAttribute 基底クラスから派生した MeshVertexAttribute クラスと ShaderVertexAttribute クラスに分割されます。

  • Texture::CreateInfo を変更しました。

  • Texture::calculateMipmapLevelCount は calculateMipmapLevelCount に変更されました。

  • 列挙型 Usage は Surface から Framebuffer クラスに移動しました。

  • プロパティ通知ハンドラのコールバックシグネチャを変更しました:

    • 最初のパラメータを Object から PropertyObject に変更しました。

    • DataType は、サブスクライブするプロパティのデータ型を指定します。たとえば、int、float、または他のサポートされているデータ型を使用します。

    • KzuPropertyNotificationReason を PropertyNotificationReason に変更しました。

    Callback(PropertyObject& object, DataType& data, PropertyNotificationReason reason, void* userData)

関連項目

Kanzi 3.6 リリースノート

既知の問題