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

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

プロジェクトおよびプラグインのテンプレート構造の変更

Kanzi 3.9 から Kanzi 4.1.0 に移行する場合、プロジェクトおよびプラグインのテンプレート構造は Kanzi 3.9 と Kanzi 4 の間で大幅に変更されています。このガイドの API の変更を適用しても、周辺のビルド構造 (CMake ファイル、ビルドスクリプト、プラットフォーム構成、およびプラグインのビルド設定) は自動的には移行されません。ビルド構造を移行する手順については、Kanzi 3.9 から Kanzi 4 へのプロジェクトの移行 を参照してください。

プロパティタイプの変更

名前が同一で設定が競合する動的プロパティタイプを作成しても、すぐにエラーがスローされなくなりました。Kanzi Engine は、最初の動的プロパティタイプの設定を保持することで、まず回復を試みます。新しく作成されたプロパティタイプは破棄されます。

次の場合は回復できません。 - 新しく作成された PropertyType のデータタイプが、同じ名前を持つ既存のプロパティタイプと異なる場合。 - 静的な PropertyType<DataType> オブジェクトを使用して、コードでプロパティタイプを作成している場合。

これらの場合は引き続きエラーがスローされます。この回復は、.kzb ファイルから読み込まれたプロパティタイプを対象としています。

不一致はすべて、ログに警告として報告されます。

プロパティタイプに関連する変更は、他にも次のような影響があります。

• AbstractRange インターフェイスに新しい関数 virtual bool equalsOverride(const AbstractRange& other) const が追加されました。継承するレンジはこの関数を実装する必要があります。

  TypedValueRange<T> で使用する新しいタイプを宣言する場合は、そのタイプに対して template <> kanzi::detail::propertyDataValueEquals(const T&, const T&) を実装する必要があります。

• Kanzi の基本データタイプには、それぞれ kanzi:: ネームスペース内に関連付けられた to_string() 関数が追加されました。

ビルドシステムの変更点

• CMake の最小必要バージョンが 3.25 に引き上げられました。

  Android プロジェクトでは、Gradle が使用する CMake のバージョンを 3.30.5 に設定することをお勧めします。これは Android SDK が提供する互換性のある最も低いバージョンです。または、カスタムの CMake を PATH 環境変数に追加することもできます。Gradle で CMake のバージョンを指定するには、Application/configs/platforms/android_gradle/kanzinative/build.gradle ファイルを次のように更新します。

  android {
    externalNativeBuild {
      cmake {
        ---------------
        version '3.30.5'
      }
    }
  }
  

• CMake ポリシー CMP0144 に準拠するため、KANZI_ROOT CMake 変数の名前が Kanzi_ROOT に変更されました。このポリシーでは、<PackageName>_ROOT ヒント変数の大文字と小文字の表記が find_package() の呼び出しで使用される表記と一致している必要があります。

  CMake のコマンドラインで -DKANZI_ROOT=<path> を渡している場合、環境で KANZI_ROOT を設定している場合、または CMakeLists.txt で KANZI_ROOT を参照している場合は、その名前を Kanzi_ROOT に変更してください。

  Kanzi 4.0	Kanzi 4.1
  -DKANZI_ROOT=<path>	-DKanzi_ROOT=<path>
  set(KANZI_ROOT <path>)	set(Kanzi_ROOT <path>)
  $ENV{KANZI_ROOT}	$ENV{Kanzi_ROOT}

Renderer API の変更

• GPUBuffer は GPUResource から派生するようになり、リソースプロパティタイプのプロパティ値として使用できるようになりました。

  GPUResource から多くの関数が削除されました。特に setData() と setSubData() が削除されています。GPUResource の GPU 側のコンテンツをアップデートするには、gfx コマンドを使用して、ハンドルでバッファーをマップするか、ステージングバッファーを割り当ててコピーします。kanzi::CommandRecorder::updateBuffer() を使用することもできます。

  また、updateGPUBufferData が追加され、バッファーを簡単にアップデートするために使用できます。内部的には kanzi::CommandRecorder::updateBuffer() を呼び出します。

  また、setGPUBufferData が追加され、以前のバッファーのサイズに関係なく、GPUBuffer をまったく新しいデータで簡単にアップデートするために使用できます。内部的には CommandRecorder を使用してバッファーのコンテンツをアップデートします。

• RenderState::HandleType は RenderStateHandle になりました。その invalid ステートは -1 ではなくなりました。代わりに RenderStateHandle::Invalid を使用してください。

• RenderPass::CameraSettings::initializeFromLight 関数のシグネチャを変更しました。

  ディレクショナルシャドウの投影フィッティングの自動化をサポートするため、Renderer リファレンスを削除し、RenderPass リファレンスを追加しました。

• kanzi::BindingRenderValueLookupContext は BindingGraphicsEntryLookupContext に名前が変更されました。

  Kanzi 4.0	Kanzi 4.1
  BindingRenderValueLookupContext	BindingGraphicsEntryLookupContext

Mesh::CreateInfo と頂点ヘルパー API の変更

Mesh::CreateInfo は、頂点データを単一のインターリーブされたブロブとしてではなく、アトリビュートごとに所有するように再構成されました。いくつかのフリーヘルパー関数と 1 つの Mesh アクセサーが削除されました。

• Mesh::CreateInfo::vertexData と Mesh::CreateInfo::vertexBufferHandle は削除されました。ソース頂点データと事前に作成されたバッファーハンドルは、各 MeshVertexAttribute の initialData フィールドと bufferHandle フィールドに格納されるようになりました。

  // Before
  Mesh::CreateInfo createInfo;
  createInfo.vertexData = ...;          // single interleaved blob
  createInfo.vertexBufferHandle = ...;
  
  // After — set per-attribute
  auto& positionAttr = createInfo.vertexFormat.attributes[0];
  positionAttr.initialData = ...;       // bytes for this attribute only
  positionAttr.bufferHandle = ...;
  

• MeshVertexAttribute::stride は削除されました。ストライドはフォーマットから導出します。

  // Before
  auto stride = attr.stride;
  // After
  auto stride = gfx::getPixelStride(attr.format);
  

• MeshVertexAttribute::dataType と MeshVertexAttribute::dimension は、単一の gfx::Format フィールドに置き換えられました。従来の (dataType, dimension) ペアを個別に変換するには、ヘルパー toKzGfx(dataType, dimension) を使用します。

  // Before
  attr.dataType = GraphicsDataTypeF32;
  attr.dimension = 3;
  // After
  attr.format = gfx::Format::RGB32_Float;
  

• 引数なしの Mesh::getVertexData() は削除されました。保持された頂点データを取得するには、アトリビュートごとのオーバーロードを使用します。

  // Before
  const auto& data = mesh.getVertexData();
  // After
  const auto& data = mesh.getVertexData(VertexAttribute::SemanticPosition);
  

• Mesh::VertexBufferContainer の値の型が Mesh::VertexData { GPUBufferSharedPtr buffer; uint32_t stride; } から GPUBufferSharedPtr に変更されました。ストライドはアトリビュートのフォーマットから導出されます。バッファーには直接アクセスします。

  // Before
  for (const auto& [key, vd] : mesh.getVertexBuffers()) { use(vd.buffer); }
  // After
  for (const auto& [key, buffer] : mesh.getVertexBuffers()) { use(buffer); }
  

• adjustForDeviceCapabilities は、調整内容を表す vector<Mesh::CreateInfo::Adjustment> を返すようになりました（以前は void）。戻り値を無視する既存の呼び出し箇所は、変更なしでコンパイルできます。

• パイプラインの検証で、UNorm/SNorm/UFloat チャンネルタイプが、シェーダーの float 入力、ColorRGBA クリア値、および ColorRGBA サンプラーボーダーカラーと互換性があるものとして扱われるようになりました。これは制約の緩和です。検証を通すためにクリア値やボーダーカラーを誤って分類せざるを得なかったコードでは、その回避策が不要になります。

• gfx::reflection::ReflectionInfo::inputAttributes と outputAttributes は、アトリビュート名を gfx::reflection::TypeInfo に直接マップするのではなく、gfx::reflection::Attribute （{ location, component, typeInfo }）にマップするようになりました。リフレクションされた型を読み取るコードは、.typeInfo を経由する必要があります。

  Kanzi 4.0	Kanzi 4.1
  attribute.second.type	attribute.second.typeInfo.type
  attribute.second.rows	attribute.second.typeInfo.rows
  attribute.second.columns	attribute.second.typeInfo.columns
  attribute.second.arraysize	attribute.second.typeInfo.arraysize

  レンダリング時に、BeginRenderPipelineCommand の処理で、バインドされた各カラーアタッチメントのブレンドステートの書き込みマスクを、リフレクションされたフラグメント出力およびバインドされたアタッチメントのチャンネルセットと照合して検証するようになりました。ブレンドステートが、フラグメントシェーダーが出力しないチャンネルへの書き込みを有効にしていて、 かつ バインドされたアタッチメントにそれらのチャンネルがある場合、バリデーターは commands-color-write-mask-mismatch を報告します。バインドされたアタッチメントにないチャンネルを対象とする書き込みマスクのビットは、仕様上ハードウェアでは何も行わないため（Vulkan、シェーダーインターフェイス — フラグメント出力インターフェイス、OpenGL 4.6 Core、§17.4.2 バッファー更新の詳細な制御）、報告されません。アタッチメントを過剰にバインドしている既存のパイプラインでは、シェーダーが書き込まないチャンネルがバインドされたアタッチメントに存在する場合に限り、それらのチャンネルの colorWriteMask をクリアする必要があります。

• DrawObjectsRenderPass::ViewportProperty は RenderPass ベースクラスに移動し、名前が RenderPass::OutputViewportProperty に変更されました。このプロパティは、ドローオブジェクトレンダーパスだけでなく、すべてのレンダーパスで使用できるようになりました。基になるプロパティ識別子は "DrawObjectsRenderPass.Viewport" から "DrawObjectsRenderPass.OutputViewport" に変更されました。以前の識別子が新しいプロパティのレガシー名として登録されているため、既存のシリアライズ済みアセットは引き続き読み込まれます。Java または Lua API を使用するプロジェクトでは、DrawObjectsRenderPassMetadata ではなく RenderPassMetadata を介してこのプロパティにアクセスする必要があります。

  Kanzi 4.0	Kanzi 4.1
  DrawObjectsRenderPass::ViewportProperty	RenderPass::OutputViewportProperty

• 次の Mesh メソッドは、アクセスする頂点アトリビュートを識別するための VertexAttribute::SemanticKey パラメーターを受け取るようになりました：Mesh::getVertexBufferHandle、Mesh::getVertexBuffer、Mesh::setVertexData、Mesh::setVertexSubData。

  VertexAttribute::Semantic パラメーターを指定して Mesh::getVertexBuffer を呼び出し、指定したセマンティックに一致する最初のアトリビュートの頂点バッファーを取得することもできます。

  Kanzi 4.0	Kanzi 4.1
  mesh.getVertexBufferHandle()	mesh.getVertexBufferHandle({ VertexAttribute::SemanticPosition, 0u })
  mesh.getVertexBuffer()	mesh.getVertexBuffer({ VertexAttribute::SemanticPosition, 0u })
  mesh.setVertexData(data)	mesh.setVertexData(data, { VertexAttribute::SemanticPosition, 0u })
  mesh.setVertexSubData(data, offset)	mesh.setVertexSubData(data, offset, { VertexAttribute::SemanticPosition, 0u })

• kanzi::Renderer::setLogging を削除しました。このメソッドは Kanzi グラフィックスへの移行以降、何も処理を行っていませんでした。アプリケーションのコードから renderer.setLogging() の呼び出しをすべて削除してください。グラフィックス API 呼び出しのロギングは、今後のリリースで再実装される予定です。

• kanzi::Renderer::getLogging と kanzi::Renderer::getDumpStateOnDrawCalls を削除しました。アプリケーションのコードから renderer.getLogging() と renderer.getDumpStateOnDrawCalls() の呼び出しをすべて削除してください。

ランタイム API の変更点

TaskDispatcherBase is now merged into TaskDispatcher, which is now moved from kanzi/core.ui/platform/task_dispatcher/common/task_dispatcher.hpp to kanzi/core.ui/task_dispatcher/task_dispatcher.hpp.

移行手順：

• task_dispatcher.hpp のインクルードディレクティブをすべて新しいロケーションにアップデートします。

• コードで TaskDispatcherBase を参照している場合は、TaskDispatcher にリプレイスします。

Platform クラスとその派生クラスであるプラットフォーム固有のクラスは、PlatformContext サフィックスを使用する名前にリネームされました。

移行手順：

• Platform を platform::PlatformContext に置き換え、インクルードディレクティブを更新します。

  Kanzi 4.0	Kanzi 4.1
  kanzi/platform/kz_platform/kz_platform.hpp	kanzi/platform/platform_context/platform_context.hpp

• プラットフォーム管理関数をリプレイスします。

  Kanzi 4.0	Kanzi 4.1
  createDefaultPlatform	platform::createDefaultPlatformContext
  destroyDefaultPlatform	platform::destroyDefaultPlatformContext
  getDefaultPlatform	platform::getDefaultPlatformContext

• カスタムプラットフォームを実装している場合は、サブクラスをリネームします。ヘッダーも同じパターンに従います。kz_platform/<custom_name>/<custom_name>_platform.hpp を platform_context/<custom_name>/<custom_name>_platform_context.hpp にリプレイスします。

  Kanzi 4.0	Kanzi 4.1
  AndroidPlatform	platform::AndroidPlatformContext
  EmscriptenPlatform	platform::EmscriptenPlatformContext
  MacosPlatform	platform::MacosPlatformContext
  QnxPlatform	platform::QnxPlatformContext
  StubPlatform	platform::StubPlatformContext
  WaylandPlatform	platform::WaylandPlatformContext
  Win32Platform	platform::Win32PlatformContext
  X11Platform	platform::X11PlatformContext

GlContextApi クラスとその派生クラスであるプラットフォーム固有のクラスは、GlGraphicsContext サフィックスを使用する名前に変更されました。ファクトリー関数 createDefaultGlContextApi は platform::makeDefaultGlGraphicsContext に名前が変更されました。

移行手順：

• GlContextApi を platform::GlGraphicsContext に置き換え、インクルードディレクティブを kanzi/platform/context/gl_context_api.hpp から kanzi/platform/platform/gl/common/gl_graphics_context.hpp に更新してください。

• ファクトリー関数の呼び出し createDefaultGlContextApi を platform::makeDefaultGlGraphicsContext に置き換えてください。

• platform::PlatformContext インスタンスで、getGlContextApi() を getGlGraphicsContext() に置き換えてください。

• GlContextApi をサブクラス化してカスタム OpenGL コンテキストを実装している場合は、クラスをリネームします。ヘッダーも同じパターンに従います。context/<name>/<name>_context_api.hpp を platform/gl/graphics_context/<name>/<name>_graphics_context.hpp に置き換えます。

  Kanzi 4.0	Kanzi 4.1
  EglContextApi	platform::EglGraphicsContext
  EglEmscriptenContextApi	platform::EglEmscriptenGraphicsContext
  EglOhosContextApi	platform::EglOhosGraphicsContext
  EglQnxStreamsContextApi	platform::EglQnxStreamsGraphicsContext
  GlxContextApi	platform::GlxGraphicsContext
  WglContextApi	platform::WglGraphicsContext

platform::GlGraphicsContext のメンバー関数 getOGLProcAddress は getGLProcAddress に名前が変更されました。

移行するには、呼び出しをリネームします。カスタム OpenGL コンテキストを実装している場合は、オーバーライドも同様にリネームします。

Kanzi 4.0	Kanzi 4.1
getOGLProcAddress	getGLProcAddress

getGLProcAddress の結果を自分で関数ポインター型に型変換する代わりに、新しい getGLProcAddressInto メンバー関数を使用できます。この関数は、渡されたポインターから関数シグネチャを推論し、読み込んだエントリーポイントを格納して、エントリーポイントが見つかったかどうかを返します。

kzplatform ライブラリの再編成に合わせて、いくつかのプラットフォーム API ヘッダーが移動されました。

移行するには、古いパスを参照しているインクルードディレクティブをアップデートします。

• kanzi/platform/kz_platform_api.hpp -> kanzi/platform/platform_api.hpp

• kanzi/platform/graphics/platform_types.hpp -> kanzi/platform/graphics/graphics_types.hpp

• kanzi/platform/platform_events.hpp -> kanzi/platform/log/platform_events.hpp

• kanzi/platform/utilities/utilities.hpp -> kanzi/platform/windowing_ng/native_accessors.hpp

• kanzi/platform/context/vulkan_functions.hpp -> kanzi/platform/platform/vulkan/common/vulkan_functions.hpp

• kanzi/platform/graphics/ 内の次のヘッダーは kanzi/platform/graphics_output/ に移動されました: graphics_output.hpp、framebuffer_graphics_output.hpp、windowed_graphics_output.hpp

• kanzi/platform/graphics/make_default_graphics_output.hpp -> kanzi/platform/target/graphics_output/make_default_graphics_output.hpp

• kanzi/platform/input/ 内の次のヘッダーは kanzi/platform/input_ng/ に移動されました: event_filter.hpp、event_queue.hpp、event_source.hpp、event_source_properties.hpp、events.hpp、input_types.hpp、wakeup_signal_source.hpp

• kanzi/platform/input/make_default_event_source.hpp -> kanzi/platform/target/input_ng/make_default_event_source.hpp

• kanzi/platform/context/ 内の次のヘッダーは kanzi/platform/windowing/ に移動されました: kzs_surface.h、kzs_surface_configuration.h

• kanzi/platform/windowing/ 内の次のヘッダーは kanzi/platform/windowing_ng/ に移動されました: native_handles.hpp、window_geometry.hpp、window_properties.hpp、window_style.hpp

• kanzi/platform/gl/ 内の次のヘッダーは kanzi/platform/platform/gl/common/ に移動されました: opengl.hpp、gl_function_pointers.hpp、gl_loaders.hpp、kzs_opengl_enum.h

アプリケーションフレームワークの変更点

• kanzi/core.ui/application/application_properties.hpp は kanzi/core.ui/graphics/renderer.hpp をインクルードしなくなりました。

  If your code includes application_properties.hpp (directly, or transitively through application.hpp) and uses Renderer or other types declared in renderer.hpp without including it directly, add an explicit include:

  #include <kanzi/core.ui/graphics/renderer.hpp>
  

• GraphicsLoggingEnabled アプリケーション構成オプション、ApplicationProperties::graphicsLoggingEnabled フィールド、および --log-graphics コマンドラインアーギュメントを削除しました。これらは Kanzi グラフィックスへの移行以降、効果がありませんでした。application.cfg ファイルから GraphicsLoggingEnabled = 1 を削除し、アプリケーションコードから ApplicationProperties::graphicsLoggingEnabled または --log-graphics への参照をすべて削除してください。

リストボックス (List Box) の変更

• トラジェクトリリストボックス (Trajectory List Box) 用に新しい TrajectoryListBoxConcept クラスと TrajectoryListBoxConceptImpl クラスを、グリッドリストボックス (Grid List Box) 用に新しい GridListBoxConceptImpl クラスを導入しました。

  既存の動作に基づいたカスタムリストボックスを簡単に実装できます。

• ListBoxTrajectoryPresenter と ListBoxGridPresenter は、派生クラスで CRTP をサポートするようになりました。

  既存の動作に基づいたカスタムプレゼンターを簡単に実装できます。

• 一貫性を保つため、すべてのリストボックスのコンセプトクラスと Impl クラスを list_box サブディレクトリに移動しました。

Android NDK バージョンの変更

• Android NDK のバージョンを 28.2.13676358 に更新し、Android 15 以降のデバイスで Google Play との互換性 のために必要な 16 KB のページサイズを Kanzi がデフォルトでサポートするようになりました。

  移行するには、アプリケーションの build.gradle ファイルで ndkVersion を 28.2.13676358 に設定してください。

マテリアル (Material) の変更

• Material クラスで、以下のパブリック (Public) メンバー関数の名前を変更しました：

  Kanzi 4.0	Kanzi 4.1
  Material::acquireDebugMaterialSolid	Material::acquireMaterialSolid
  Material::acquireDebugMaterialTextured	Material::acquireMaterialTextured

アプリケーション入力イベントの変更

• アプリケーションのステートとの一貫性を保つため、アプリケーション入力イベント sleep と wakeup の名前が paused と resumed に変更されました。コード内のイベントタイプと関数呼び出しを、新しい名前を使用するように変更してください。

  Kanzi 4.0	Kanzi 4.1
  InputEvent::Type::ApplicationSleep	InputEvent::Type::ApplicationPaused
  InputEvent::Type::ApplicationWakeup	InputEvent::Type::ApplicationResumed
  addApplicationSleepEvent()	addApplicationPausedEvent
  addApplicationWakeupEvent()	addApplicationResumedEvent

  これまで使用されていなかった InputEvent::Type::ApplicationPaused イベントは、アプリケーションが一時停止され、MainLoopState::Paused に遷移したことを通知するようになりました。このイベントは、以前 ApplicationSleep が担っていた役割を果たします。

マテリアルタイプコマンドの変更

• SaveMaterialType コマンドを削除しました。プロジェクト間でマテリアルタイプを共有するには、代わりに ExportProjectItems を使用してください。

• LoadMaterialType コマンドは非推奨になりました。.kzexport アーカイブからマテリアルタイプをインポートするには、代わりに ImportProjectItems を使用してください。

TextBoxConcept API の変更

• TextBoxConcept のメッセージアーギュメントのメタクラスの名前を、それを含むクラスの名前と一致するように変更しました。

  Kanzi Engine Lua API および Kanzi Java API アプリケーションを移行するには、TextBoxMetadata の名前を TextBoxConceptMetadata に変更してください。

TextInputManipulator API の変更

• TextInputManipulator のメッセージアーギュメントのメタクラスの名前を、それを含むクラスの名前と一致するように変更しました。

  Kanzi Engine Lua API および Kanzi Java API アプリケーションを移行するには、TextInputConceptMetadata の名前を TextInputManipulatorMetadata に変更してください。

Kanzi Engine Lua API の変更

• PropertyType:new メソッドと MessageType:new メソッドを非推奨にし、PropertyType:find と MessageType:find に置き換えました。

  Kanzi Engine Lua API スクリプトを移行するには、PropertyType:new の名前を PropertyType:find に、MessageType:new の名前を MessageType:find に変更してください。

• Lua の複数のコンストラクターの名前を create から create1 に変更しました。

  Kanzi 4.0	Kanzi 4.1
  CallbackBindingProcessor:create	CallbackBindingProcessor:create1
  NodeEffectPrefab2D:create	NodeEffectPrefab2D:create1
  RangeBindingProcessor:create	RangeBindingProcessor:create1
  RenderPassPrefab:create	RenderPassPrefab:create1

プラットフォームの変更

• listEGLAttributes を削除し、より柔軟な formatEGLAttributes に置き換えました。この関数は、人間が読みやすい形式にフォーマットされた文字列を作成します。

  移行するには、formatEGLAttributes を使用してアトリビュートをフォーマットし、フォーマットされた文字列を kzLogInfo に渡してください。

  // Before migration.
  listEGLAttributes("EGL context attributes", attribs);
  
  // After migration.
  kzLogInfo(KZ_LOG_CATEGORY_EGL, ("{}", formatEGLAttributes("EGL context attributes", attribs)));
  

• platform::createDefaultPlatformContext、platform::destroyDefaultPlatformContext、および platform::getDefaultPlatformContext は、platform_context.hpp から新しい専用ヘッダーに移動しました。

  移行するには、インクルードを更新します。

  // Before migration.
  #include <kanzi/platform/platform_context/platform_context.hpp>
  
  // After migration.
  #include <kanzi/platform/target/platform_context/default_platform_context.hpp>
  

PropertyFieldAnimationTimelinePlayback の変更点

PropertyFieldAnimationTimelinePlayback の protected コンストラクターに新しいパラメーターが追加されました。

// Kanzi 4.0
explicit PropertyFieldAnimationTimelinePlayback(
    PropertyFieldAnimationTimelineSharedPtr, ObjectSharedPtr, bool relative);

// Kanzi 4.1
explicit PropertyFieldAnimationTimelinePlayback(
    PropertyFieldAnimationTimelineSharedPtr, ObjectSharedPtr, bool relative,
    const optional<TimelinePlaybackContext::RuntimeEnvironment>& runtimeEnv);

PropertyFieldAnimationTimelinePlayback をサブクラス化して protected コンストラクターを直接呼び出している場合は、以前の動作を維持するために runtimeEnv に nullopt を渡してください。

また、このクラスのコピーコンストラクター、ムーブコンストラクター、およびコピー代入演算子とムーブ代入演算子は、明示的に削除されるようになりました。

PipelineStateRenderPass のカラーライトモードの変更点

• GraphicsColorWriteMode エヌメレーションは削除され、gfx::ColorWriteMask に置き換えられました。これは、個々のチャンネルフラグを組み合わせることができるビットマスクフラグ型です。

  PipelineStateRenderPass::ColorWriteModeProperty の型は、PropertyType<GraphicsColorWriteMode> から kanzi::PropertyType<kanzi::gfx::ColorWriteMask> に変更されました。getColorWriteMode() および setColorWriteMode() アクセサーは gfx::ColorWriteMask を使用するようになりました。

  gfx::ColorWriteMask はビットマスクであるため、ビット単位の OR 演算子を使用してチャンネルフラグを組み合わせることができます。

  // Kanzi 4.0
  renderPass->setColorWriteMode(GraphicsColorWriteModeRGBA);
  
  // Kanzi 4.1
  renderPass->setColorWriteMode(gfx::ColorWriteMask::RGBA);
  renderPass->setColorWriteMode(gfx::ColorWriteMask::R | gfx::ColorWriteMask::G);
  

  次の表は、以前のエヌメレーション値と、それに相当する新しいフラグの対応を示しています。

  Kanzi 4.0 (GraphicsColorWriteMode)	Kanzi 4.1 (gfx::ColorWriteMask)
  GraphicsColorWriteModeNone	gfx::ColorWriteMask::None
  GraphicsColorWriteModeRGB	gfx::ColorWriteMask::RGB
  GraphicsColorWriteModeRGBA	gfx::ColorWriteMask::RGBA
  GraphicsColorWriteModeR	gfx::ColorWriteMask::R | gfx::ColorWriteMask::A
  GraphicsColorWriteModeG	gfx::ColorWriteMask::G | gfx::ColorWriteMask::A
  GraphicsColorWriteModeB	gfx::ColorWriteMask::B | gfx::ColorWriteMask::A
  GraphicsColorWriteModeGB	gfx::ColorWriteMask::G | gfx::ColorWriteMask::B | gfx::ColorWriteMask::A
  GraphicsColorWriteModeA	gfx::ColorWriteMask::A

  注釈

  エヌメレーションの整数値が変更されました。新しい型では、以前の連番インデックスではなく、2 の累乗のビットマスク値 (R=1、G=2、B=4、A=8) を使用します。GraphicsColorWriteMode の生の整数値を保存または比較しているアプリケーションコードを更新してください。.kzm プロジェクトファイルは、Kanzi Studio 4.1 で開くと自動的に移行されます。

• Kanzi Studio のプラグインインターフェイスでは、PipelineStateRenderPassColorWriteMode が TypedProperty<ColorWriteModeEnum> から TypedProperty<int> に変更され、ColorWriteModeEnum 型は削除されました。このプロパティを読み書きするプラグインコードを、生の整数フラグ値 (Red=1、Green=2、Blue=4、Alpha=8) を使用するように更新してください。

• Kanzi Engine Lua API では、削除された GraphicsColorWriteMode テーブルを gfx.ColorWriteMask に置き換えてください。

  Kanzi 4.0 (GraphicsColorWriteMode)	Kanzi 4.1 (gfx.ColorWriteMask)
  GraphicsColorWriteMode.GraphicsColorWriteModeNone	gfx.ColorWriteMask.None
  GraphicsColorWriteMode.GraphicsColorWriteModeRGBA	gfx.ColorWriteMask.RGBA
  GraphicsColorWriteMode.GraphicsColorWriteModeRGB	gfx.ColorWriteMask.RGB
  GraphicsColorWriteMode.GraphicsColorWriteModeR	gfx.ColorWriteMask.R | gfx.ColorWriteMask.A
  GraphicsColorWriteMode.GraphicsColorWriteModeG	gfx.ColorWriteMask.G | gfx.ColorWriteMask.A
  GraphicsColorWriteMode.GraphicsColorWriteModeB	gfx.ColorWriteMask.B | gfx.ColorWriteMask.A
  GraphicsColorWriteMode.GraphicsColorWriteModeGB	gfx.ColorWriteMask.G | gfx.ColorWriteMask.B | gfx.ColorWriteMask.A
  GraphicsColorWriteMode.GraphicsColorWriteModeA	gfx.ColorWriteMask.A

• Kanzi Java API では、GraphicsColorWriteMode を ColorWriteMask に置き換え、PipelineStateRenderPassMetadata.ColorWriteModeProperty への参照もそれに合わせて更新してください。

• PipelineStateRenderPass.ColorWriteMode の値を含む .kzm プロジェクトファイルは、Kanzi Studio 4.1 で開くと新しいフラグ表現に自動的に移行されます。

Kanzi Documentation MCP サーバーの変更

新しい統合 Kanzi Documentation MCP サーバーが https://docs.mcp.kanzi.com/mcp で利用可能になり、Claude Desktop 用の新しい mcpb バンドルが https://docs.kanzi.com/mcp/kanzi-docs-mcp.zip で提供されています。新しいエンドポイントは、ロードされているすべての Kanzi バージョンをサポートします。

既存のバージョン固有の URL (kanzi-docs-mcp-v3-9.* および kanzi-docs-mcp-v4-0.*) も引き続きサポートされます。新しい統合を使用するには、統合 URL に移行してください。Kanzi ドキュメント MCP サーバー を参照してください。

以前に MCP クライアントの設定にバージョン固有のエントリ (kanzi-docs-v3-9 や kanzi-docs-v4-0 など) を追加していた場合は、統合 kanzi-docs エントリを追加した後にそれらを削除してください。重複したエントリを残しておくと、クライアントの起動がハングすることがあります。

シェーダーコンパイルの変更

Kanzi 4.1.0 以降、マテリアル内のシェーダーの ソースコード には GLSL ES 310 以降またはデスクトップ GLSL 140 以降の構文を使用する必要があります。従来の GLSL 構文 (attribute、varying、gl_FragColor、gl_FragData[N]) は使用できなくなりました。Kanzi Studio プロジェクト内で従来の構文を使用しているシェーダーは更新する必要があります。

これはシェーダーの 作成 に関する要件の変更であり、デプロイに関する変更ではありません。Kanzi はシェーダーソースを、プロジェクトの Target Graphics API 設定で必要とされる GLSL 方言にクロスコンパイルするため、引き続き OpenGL ES 3.0 にデプロイできます。例外は、シェーダーが GLSL ES 3.1 以降で導入された機能 (コンピュートシェーダー、イメージのロード/ストア、シェーダーストレージバッファオブジェクトなど) を使用している場合です。ソースで使用する機能は、選択した Target Graphics API で利用可能である必要があります。

シェーダーを移行するには、以下の変換を適用します。

従来の構文	置き換え後
attribute	in (バーテックスシェーダーの入力)
varying (バーテックスシェーダー)	out (バーテックスシェーダーの出力)
varying (フラグメントシェーダー)	in (フラグメントシェーダーの入力)
gl_FragColor	layout(location = 0) out vec4 fragColor; で宣言したユーザー定義の出力変数
gl_FragData[N]	layout(location = N) out vec4 fragDataN; で宣言したユーザー定義の出力変数
#version がない	#version 310 es (組み込みシステム) または #version 460 (デスクトップ) を追加
#version 100 または #version 300 es	#version 310 es
main() 内の precision	precision を main() より前のグローバルスコープに移動します。ES 310 では、フラグメントシェーダーの浮動小数に対するグローバルな精度指定が必要です。
texture2D(sampler, uv)	texture(sampler, uv)
textureCube(sampler, uv)	texture(sampler, uv)

その他の考慮事項:

• 名前付きユニフォームブロックでは、明示的なレイアウト修飾子を使用する必要があります。uniform BlockName { ... }; を layout(std140, binding = N, set = M) uniform BlockName { ... }; に置き換えてください。

• Kanzi は、個別のユニフォーム (uniform float Opacity; など) を保持する自動生成ユニフォームブロック用に、ディスクリプターセット 0、バインディング 0 を予約しています。セット 0、バインディング 0 でカスタムユニフォームブロックを使用するマテリアルタイプがある場合は、そのブロックを別のバインディングに移動してください。

• Project Properties で選択した Target Graphics API によって、使用できる ES 310 / GL 140 の機能が制限されます。コンピュートシェーダー、イメージのロード/ストア、シェーダーストレージバッファオブジェクトを使用するには、Target Graphics API が OpenGL ES 3.1 以降 (またはデスクトップの同等のもの) である必要があります。ES 310 の 構文 (in / out、texture()、名前付き出力変数) のみを使用するシェーダーは、引き続き OpenGL ES 3.0 ターゲット向けに問題なくクロスコンパイルされます。

更新されたシェーダー作成のリファレンスについては、OpenGL ES バージョンを設定する を参照してください。

関連項目

Kanzi 4.1.0 リリースノート

既知の問題