3D アプリ ランチャー (Win32 アプリ) の実装します。Implement 3D app launchers (Win32 apps)

注意

この機能は、最新バージョンを実行しているコンピューターのみWindows Insiderフライト (RS5)、17704 と新しいビルドします。This feature is only available to PCs running the latest Windows Insider flights (RS5), build 17704 and newer.

Windows Mixed Reality ホーム始めるユーザーがアプリケーションを起動する前に配置する場所です。The Windows Mixed Reality home is the starting point where users land before launching applications. 既定では、没入型の Win32 VR アプリやゲームはヘッドセットの外部から起動する必要があるし、Windows Mixed Reality スタート メニューのすべてのアプリ 一覧に表示されません。By default, immersive Win32 VR apps and games have to be launched from outside the headset and won't appear in the "All apps" list on the Windows Mixed Reality Start menu. ただし、3D アプリ ランチャーを実装するためには、この記事の手順では、Win32 VR エクスペリエンスを作り出すから起動できます Windows Mixed Reality スタート メニューとホーム環境にします。However, by following the instructions in this article to implement a 3D app launcher, your immersive Win32 VR experience can be launched from within the Windows Mixed Reality Start menu and home environment.

ストリームの外部での Win32 VR エクスペリエンス distributied の没入型の場合のみです。This is only true for immersive Win32 VR experiences distributied outside of Steam. VR エクスペリエンスのため蒸気経由で配布、しましたSteamVR ベータ版の Windows Mixed Reality を更新最新の Windows Insider RS5 と共に、Windows での表示をタイトル SteamVR ようにのフライト既定の起動ツールを使用して自動的にすべてのアプリ] 一覧で混合の実際には [スタート] メニューは。For VR experiences distributed through Steam, we've updated the Windows Mixed Reality for SteamVR Beta along with the latest Windows Insider RS5 flights so that SteamVR titles show up in the Windows Mixed Reality Start menu in the "All apps" list automatically using a default launcher. つまり、この記事で説明されているメソッドでは、SteamVR タイトルの必要はありませんし、SteamVR ベータ機能の Windows Mixed Reality によってオーバーライドされます。In other words, the method described in this article is unnecessary for SteamVR titles and will be overridden by the Windows Mixed Reality for SteamVR Beta functionality.

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

3D アプリ起動ツールを作成する 3 つの手順があります。There are 3 steps to creating a 3D app launcher:

  1. デザインと conceptingDesigning and concepting
  2. モデリングとエクスポートModeling and exporting
  3. (この記事)、アプリケーションに統合します。Integrating it into your application (this article)

3D アセットを使用して、アプリケーションの起動ツールを作成する必要がありますとして使用する、ガイドラインの authoring Windows Mixed Reality互換性を確保します。3D assets to be used as launchers for your application should be authored using the Windows Mixed Reality authoring guidelines to ensure compatibility. このオーサリングの仕様を満たすために失敗した資産は、ホーム Windows Mixed Reality ではレンダリングされません。Assets that fail to meet this authoring specification will not be rendered in the Windows Mixed Reality home.

3D の起動ツールを構成します。Configuring the 3D launcher

Win32 アプリケーションは、3 D のアプリ起動ツールを作成する場合、Windows Mixed Reality スタート メニューのすべてのアプリ 一覧に表示されます。Win32 applications will appear in the "All apps" list on the Windows Mixed Reality Start menu if you create a 3D app launcher for them. 作成、 Visual 要素マニフェスト次の手順で 3D アプリ起動ツールを参照する XML ファイル。To do that, create a Visual Elements Manifest XML file referencing the 3D App Launcher by following these steps:

  1. 作成、 3D アプリ起動ツール資産 GLB ファイル(を参照してくださいモデリングおよびエクスポート)。Create a 3D App Launcher asset GLB file (See Modeling and exporting).
  2. 作成、 Visual 要素マニフェスト アプリケーション用。Create a Visual Elements Manifest for your application.
    1. 使用することができます、以下のサンプルします。You can start with the sample below. 完全を参照してください。 Visual 要素マニフェスト詳細についてはドキュメントです。See the full Visual Elements Manifest documentation for more details.
    2. 更新Square150x150LogoSquare70x70Logo PNG/JPG または gif 形式、アプリを使用します。Update Square150x150Logo and Square70x70Logo with a PNG/JPG/GIF for your app.
      • これらは、Windows Mixed Reality のすべてのアプリの一覧で、アプリの 2D ロゴおよびデスクトップで [スタート] メニューに使用されます。These will be used for the app’s 2D logo in the Windows Mixed Reality All Apps list and for the Start Menu on desktop.
      • ファイルのパスでは、ビジュアル要素マニフェストを含むフォルダーの相対パスです。The file path is relative to the folder containing the Visual Elements Manifest.
      • 標準のメカニズムを通じて、アプリ、デスクトップの [スタート] メニューのアイコンを指定する必要があります。You still need to provide a desktop Start Menu icon for your app through the standard mechanisms. 実行可能ファイルなのか (例: IShellLink::SetIconLocation) 経由で作成したショートカットを指定できます。This can either be directly in the executable or in the shortcut you create (e.g. via IShellLink::SetIconLocation).
      • 省略可能。 別の解像度のスケールとハイ コントラスト テーマの複数の資産のサイズを指定する MRT に必要な場合は、resources.pri ファイルを使用できます。Optional: You can use a resources.pri file if you would like for MRT to provide multiple asset sizes for different resolution scales and high contrast themes.
    3. 更新プログラム、 MixedRealityModel パスGLB を指す、3D アプリ起動ツールのUpdate the MixedRealityModel Path to point to the GLB for your 3D App Launcher
    4. 拡張機能で、実行可能ファイルと同じ名前のファイルを保存"します。VisualElementsManifest.xml"と同じディレクトリに保存します。Save the file with the same name as your executable file, with an extension of ".VisualElementsManifest.xml" and save it in the same directory. たとえば、"contoso.exe"実行可能ファイルの付随する XML ファイルの名前は"contoso.visualelementsmanifest.xml"。For example, for the executable file "contoso.exe", the accompanying XML file is named "contoso.visualelementsmanifest.xml".
  3. ショートカットを追加するデスクトップでの Windows の [スタート] メニューをアプリケーションにします。Add a shortcut to your application to the desktop Windows Start Menu. 参照してください、以下のサンプル例については、C++実装します。See the sample below for an example C++ implementation.
    • %ALLUSERSPROFILE%\Microsoft\Windows\Start menu \programs (コンピューター) または %APPDATA%\Microsoft\Windows\Start menu \programs (ユーザー) で作成します。Create it in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (machine) or %APPDATA%\Microsoft\Windows\Start Menu\Programs (user)
    • 視覚的要素マニフェストまたはその参照先資産の更新プログラムが変更された場合 updater またはインストーラーする必要がありますショートカットを更新、マニフェストが再解析され、キャッシュしたアセットが更新されるようにします。If an update changes your visual elements manifest or the assets referenced by it, the updater or installer should update the shortcut such that the manifest is reparsed and cached assets are updated.
  4. 省略可能。 デスクトップ ショートカットが、アプリケーションの EXE の直接を指していないかどうか (などのカスタム プロトコル ハンドラーを呼び出す場合など、"myapp://")、[スタート] メニューは、アプリの VisualElementsManifest.xml ファイルに自動的に検出しません。Optional: If your desktop shortcut does not point directly to your application’s EXE (e.g., if it invokes a custom protocol handler like “myapp://”), the Start Menu won’t automatically find the app’s VisualElementsManifest.xml file. これを解決するには、ショートカットが System.AppUserModel.VisualElementsManifestHintPath () を使用して視覚的要素マニフェストのファイル パスを指定する必要があります。To resolve this, the shortcut should specify the file path of the Visual Elements Manifest using System.AppUserModel.VisualElementsManifestHintPath (). これは、System.AppUserModel.ID として同じ手法を使用して、ショートカットに設定できます。This can be set in the shortcut using the same techniques as System.AppUserModel.ID. System.AppUserModel.ID を使用する必要はありませんが、ショートカットを使用している場合、アプリケーションの明示的なアプリケーション ユーザー モデル ID に一致する場合はする可能性があります。You are not required to use System.AppUserModel.ID but you may do so if you wish for the shortcut to match the explicit Application User Model ID of the application if one is used. 参照してください、アプリ起動ツールのショートカットの作成のサンプル下の「、C++サンプル。See the sample app launcher shortcut creation section below for a C++ sample.

サンプルの Visual 要素マニフェストSample Visual Elements Manifest

<Application xmlns:xsi="http://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>

サンプル アプリ起動ツールのショートカットの作成Sample app launcher shortcut creation

次のサンプル コードでショートカットを作成する方法を示しています。 C++、などの Visual 要素マニフェスト XML ファイルへのパスをオーバーライドします。The sample code below shows how you can create a shortcut in C++, including overriding the path to the Visual Elements Manifest XML file. 場所のショートカットは、直接 (例: マニフェストに関連付けられている実行可能ファイルをポイントしていない場合、上書きが必要なだけに注意してください。Note the override is only required in cases where your shortcut does not point directly to the EXE associated with the manifest (eg. ショートカットのようにカスタム プロトコル ハンドラーを使用して"myapp://")。your shortcut uses a custom protocol handler like "myapp://").

サンプルです。LNK ショートカットの作成 (C++)Sample .LNK shortcut creation (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 のランチャー ショートカットSample .URL launcher shortcut

[{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

関連項目See also