3D アプリ起動ツールを実装する (Win32 アプリ)

[アーティクル]
02/18/2025

注:

この機能は、最新の Windows Insider フライト (RS5)、ビルド 17704 以降を実行している PC でのみ使用できます。

Windows Mixed Realityホームは、ユーザーがアプリケーションを起動する前に着陸する出発点です。既定では、ヘッドセットの外部からイマーシブ Win32 VR アプリとゲームを起動する必要があり、Windows Mixed Realityの [スタート] メニューの [すべてのアプリ] リストには表示されません。この記事の指示に従って 3D アプリ起動ツールを実装すると、Windows Mixed Realityスタートメニューとホーム環境内からイマーシブ Win32 VR エクスペリエンスを起動できます。

これは、Steam の外部で配布されるイマーシブ Win32 VR エクスペリエンスに対してのみ当てはまります。 Steam を通じて配布される VR エクスペリエンスの場合は、SteamVR ベータ版のWindows Mixed Realityと最新の Windows Insider RS5 フライトが更新され、既定の起動ツールを使用して自動的に [すべてのアプリ] リストの [Windows Mixed Reality スタート] メニューに SteamVR タイトルが表示されるようになります。つまり、この記事で説明するメソッドは SteamVR タイトルでは不要であり、SteamVR ベータ機能のWindows Mixed Realityによってオーバーライドされます。

3D アプリ起動ツールの作成プロセス

3D アプリ起動ツールを作成するには、次の 3 つの手順があります。

設計と概念
モデリングとエクスポート
アプリケーションへの統合 (この記事)

アプリケーションの起動ツールとして使用する 3D アセットは、互換性を確保するために、Windows Mixed Reality作成ガイドラインを使用して作成する必要があります。このオーサリング仕様を満たしていないアセットは、Windows Mixed Reality ホームではレンダリングされません。

3D 起動ツールの構成

Win32 アプリケーションは、3D アプリ起動ツールを作成すると、Windows Mixed Realityの [スタート] メニューの [すべてのアプリ] リストに表示されます。そのためには、次の手順に従って、3D アプリ起動ツールを参照する Visual Elements Manifest XML ファイルを作成します。

3D App Launcher アセット GLB ファイルを作成します (「モデリングとエクスポート」を参照してください)。
アプリケーションの Visual Elements マニフェスト を作成します。
1. 次のサンプルから始めることができます。詳細については、 Visual Elements マニフェストの完全なドキュメントを参照してください。
2. アプリの PNG/JPG/GIF で Square150x150Logo と Square70x70Logo を更新します。
  - これらは、[すべてのアプリ] リストのアプリの 2D Windows Mixed Reality ロゴとデスクトップの [スタート] メニューに使用されます。
  - ファイルパスは、Visual Elements マニフェストを含むフォルダーに基づいています。
  - 引き続き、標準のメカニズムを使用して、アプリのデスクトップスタートメニューアイコンを指定する必要があります。これは、実行可能ファイル内または作成したショートカット内に直接指定できます。たとえば、IShellLink::SetIconLocation を使用します。
  - 随意： MRT でさまざまな解像度スケールとハイコントラストテーマに複数のアセットサイズを提供する場合は、resources.pri ファイルを使用できます。
3. 3D アプリ起動ツールの GLB をポイントするように MixedRealityModel パス を更新します
4. 実行可能ファイルと同じ名前のファイルを、拡張子が ".VisualElementsManifest.xml" で保存し、同じディレクトリに保存します。たとえば、実行可能ファイル "contoso.exe" の場合、付随する XML ファイルの名前は "contoso.visualelementsmanifest.xml" です。
デスクトップの Windows スタートメニューにアプリケーションへのショートカットを追加します。 C++ 実装の例については、以下のサンプルを参照してください。
- %ALLUSERSPROFILE%\Microsoft\Windows\スタートメニュー\プログラム (マシン) または %APPDATA%\Microsoft\Windows\Start Menu\Programs (ユーザー) で作成します
- 更新によってビジュアル要素マニフェストまたはそれが参照する資産が変更された場合、アップデーターまたはインストーラーは、マニフェストが再解析され、キャッシュされた資産が更新されるようにショートカットを更新する必要があります。
随意： デスクトップショートカットがアプリケーションの EXE を直接指していない場合 (たとえば、"myapp://" のようなカスタムプロトコルハンドラーを呼び出した場合)、スタートメニューはアプリの VisualElementsManifest.xml ファイルを自動的に見つけることができません。これを解決するには、System.AppUserModel.VisualElementsManifestHintPath () を使用して、Visual Elements マニフェストのファイルパスをショートカットで指定する必要があります。これは、System.AppUserModel.ID と同じ手法を使用してショートカットで設定できます。 System.AppUserModel.ID を使用する必要はありませんが、ショートカットをアプリケーションの明示的なアプリケーションユーザーモデル ID と一致させる場合は、使用できます。 C++ サンプルについては、以下のサンプルアプリ起動ツールショートカット作成セクションを参照してください。

ビジュアル要素マニフェストのサンプル

<Application xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <VisualElements
    ShowNameOnSquare150x150Logo="on"
    Square150x150Logo="YOUR_APP_LOGO_150X150.png"
    Square70x70Logo=" YOUR_APP_LOGO_70X70.png"
    ForegroundText="light"
    BackgroundColor="#000000">
    <MixedRealityModel Path="YOUR_3D_APP_LAUNCHER_ASSET.glb">
        <SpatialBoundingBox Center="0,0,0" Extents="Auto" />
    </MixedRealityModel>
  </VisualElements>
</Application>

サンプルアプリ起動ツールのショートカットの作成

次のサンプルコードは、Visual Elements Manifest XML ファイルへのパスのオーバーライドなど、C++ でショートカットを作成する方法を示しています。オーバーライドは、ショートカットがマニフェストに関連付けられている EXE を直接指していない場合にのみ必要です (たとえば、ショートカットでは "myapp://" のようなカスタムプロトコルハンドラーが使用されます)。

見本。LNK ショートカットの作成 (C++)

#include <windows.h>
#include <propkey.h>
#include <shlobj_core.h>
#include <shlwapi.h>
#include <propvarutil.h>
#include <wrl.h>

#include <memory>

using namespace Microsoft::WRL;

#define RETURN_IF_FAILED(x) do { HRESULT hr = x; if (FAILED(hr)) { return hr; } } while(0)
#define RETURN_IF_WIN32_BOOL_FALSE(x) do { DWORD res = x; if (res == 0) { return HRESULT_FROM_WIN32(GetLastError()); } } while(0)

int wmain()
{
    RETURN_IF_FAILED(CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED));

    ComPtr<IShellLink> shellLink;
    RETURN_IF_FAILED(CoCreateInstance(__uuidof(ShellLink), nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&shellLink)));
    RETURN_IF_FAILED(shellLink->SetPath(L"MyLauncher://launch/app-identifier"));

    // It is also possible to use an icon file in another location. For example, "C:\Program Files (x86)\MyLauncher\assets\app-identifier.ico".
    RETURN_IF_FAILED(shellLink->SetIconLocation(L"C:\\Program Files (x86)\\MyLauncher\\apps\\app-identifier\\game.exe", 0 /*iIcon*/));

    ComPtr<IPropertyStore> propStore;
    RETURN_IF_FAILED(shellLink.As(&propStore));

    {
        // Optional: If the application has an explict Application User Model ID, then you should usually specify it in the shortcut.
        PROPVARIANT propVar;
        RETURN_IF_FAILED(InitPropVariantFromString(L"ExplicitAppUserModelID", &propVar));
        RETURN_IF_FAILED(propStore->SetValue(PKEY_AppUserModel_ID, propVar));
        PropVariantClear(&propVar);
    }

    {
        // A hint path to the manifest is only necessary if the target path of the shortcut is not a file path to the executable.
        // By convention the manifest is named <executable name>.VisualElementsManifest.xml and is in the same folder as the executable
        // (and resources.pri if applicable). Assets referenced by the manifest are relative to the folder containing the manifest.

        //
        // PropKey.h
        //
        //  Name:     System.AppUserModel.VisualElementsManifestHintPath -- PKEY_AppUserModel_VisualElementsManifestHintPath
        //  Type:     String -- VT_LPWSTR  (For variants: VT_BSTR)
        //  FormatID: {9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3}, 31
        //  
        //  Suggests where to look for the VisualElementsManifest for a Win32 app
        //
        // DEFINE_PROPERTYKEY(PKEY_AppUserModel_VisualElementsManifestHintPath, 0x9F4C2855, 0x9F79, 0x4B39, 0xA8, 0xD0, 0xE1, 0xD4, 0x2D, 0xE1, 0xD5, 0xF3, 31);
        // #define INIT_PKEY_AppUserModel_VisualElementsManifestHintPath { { 0x9F4C2855, 0x9F79, 0x4B39, 0xA8, 0xD0, 0xE1, 0xD4, 0x2D, 0xE1, 0xD5, 0xF3 }, 31 }

        PROPVARIANT propVar;
        RETURN_IF_FAILED(InitPropVariantFromString(L"C:\\Program Files (x86)\\MyLauncher\\apps\\app-identifier\\game.visualelementsmanifest.xml", &propVar));
        RETURN_IF_FAILED(propStore->SetValue(PKEY_AppUserModel_VisualElementsManifestHintPath, propVar));
        PropVariantClear(&propVar);
    }

    constexpr PCWSTR shortcutPath = L"%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\game.lnk";
    const DWORD requiredBufferLength = ExpandEnvironmentStrings(shortcutPath, nullptr, 0);
    RETURN_IF_WIN32_BOOL_FALSE(requiredBufferLength);

    const auto expandedShortcutPath = std::make_unique<wchar_t[]>(requiredBufferLength);
    RETURN_IF_WIN32_BOOL_FALSE(ExpandEnvironmentStrings(shortcutPath, expandedShortcutPath.get(), requiredBufferLength));

    ComPtr<IPersistFile> persistFile;
    RETURN_IF_FAILED(shellLink.As(&persistFile));
    RETURN_IF_FAILED(persistFile->Save(expandedShortcutPath.get(), FALSE));

    return 0;
}

見本。URL 起動ツールのショートカット

[{9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3}]
Prop31=C:\Program Files (x86)\MyLauncher\apps\app-identifier\game.visualelementsmanifest.xml
Prop5=ExplicitAppUserModelID

[{000214A0-0000-0000-C000-000000000046}]
Prop3=19,0

[InternetShortcut]
IDList=
URL=MyLauncher://launch/app-identifier
IconFile=C:\Program Files (x86)\MyLauncher\apps\app-identifier\game.exe
IconIndex=0

次の方法で共有

3D アプリ起動ツールを実装する (Win32 アプリ)

3D アプリ起動ツールの作成プロセス

3D 起動ツールの構成

ビジュアル要素マニフェストのサンプル

サンプルアプリ起動ツールのショートカットの作成

見本。LNK ショートカットの作成 (C++)

見本。URL 起動ツールのショートカット

関連項目

フィードバック

その他のリソース

次の方法で共有

3D アプリ起動ツールを実装する (Win32 アプリ)

3D アプリ起動ツールの作成プロセス

3D 起動ツールの構成

ビジュアル要素マニフェストのサンプル

サンプル アプリ起動ツールのショートカットの作成

見本。LNK ショートカットの作成 (C++)

見本。URL 起動ツールのショートカット

関連項目

フィードバック

その他のリソース

サンプルアプリ起動ツールのショートカットの作成