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

注意

この機能は、最新のWindows Insider便 (RS5)、ビルド17704以降を実行している pc でのみ使用できます。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 アプリランチャーを実装することで、Windows Mixed Reality の [スタート] メニューと [ホーム] 環境からイマーシブ Win32 VR エクスペリエンスを起動できます。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.

これは、蒸気の外部で distributied の Win32 VR エクスペリエンスを使用する場合にのみ当てはまります。This is only true for immersive Win32 VR experiences distributied outside of Steam. ストリームによって配布される VR エクスペリエンスの場合、Windows Mixed Reality For Steamvr Betaと最新の windows Insider RS5 フライトを更新しました。これにより、"すべてのアプリ" リストの windows Mixed reality の [スタート] メニューに 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 タイトルには不要であり、Windows Mixed Reality for SteamVR Beta 機能によって上書きされます。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 アセットは、互換性を確保するために、 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 アプリケーションは、Windows Mixed Reality の [スタート] メニューの [すべてのアプリ] の一覧に表示されます (3D アプリランチャーを作成した場合)。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. これを行うには、次の手順に従って、3D アプリランチャーを参照するビジュアル要素マニフェストXML ファイルを作成します。To do that, create a Visual Elements Manifest XML file referencing the 3D App Launcher by following these steps:

  1. 3D アプリランチャー ASSET GLB ファイルを作成します (「モデリングとエクスポート」を参照してください)。Create a 3D App Launcher asset GLB file (See Modeling and exporting).
  2. アプリケーションの ビジュアル要素マニフェスト を作成します。Create a Visual Elements Manifest for your application.
    1. 次のサンプルから始めることができます。You can start with the sample below. 詳細については、ビジュアル要素の完全なマニフェストに関するドキュメントを参照してください。See the full Visual Elements Manifest documentation for more details.
    2. アプリの PNG/JPG/GIF でSquare150x150LogoSquare70x70Logoを更新します。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).
      • OptionalMRT.DLL がさまざまな解像度スケールとハイコントラストテーマに対して複数のアセットサイズを提供する場合は、リソースの 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. 3D アプリランチャーの GLB をポイントするようにMixedRealityModel パスを更新します。Update the MixedRealityModel Path to point to the GLB for your 3D App Launcher
    4. "" という拡張子を持つ実行可能ファイルと同じ名前のファイルを保存します。Visualを Manifest.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. たとえば、実行可能ファイル "al.exe" の場合、付随する XML ファイルの名前は "contoso. visual、.manifest" になります。For example, for the executable file "contoso.exe", the accompanying XML file is named "contoso.visualelementsmanifest.xml".
  3. アプリケーションへのショートカットをデスクトップの [スタート] メニューに追加します。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 (machine) または%APPDATA%\Microsoft\Windows\Start Menu\Programs (user) で作成するCreate it in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (machine) or %APPDATA%\Microsoft\Windows\Start Menu\Programs (user)
    • 更新によって、ビジュアル要素マニフェストまたはそれによって参照される資産が変更された場合、更新プログラムによって、マニフェストが再解析され、キャッシュされたアセットが更新されるようにショートカットが更新されます。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. Optionalデスクトップショートカットがアプリケーションの EXE を直接指していない場合 (たとえば、"myapp://" のようなカスタムプロトコルハンドラーが呼び出された場合)、[スタート] メニューでアプリの Visual要素のマニフェストファイルが自動的に検索されません。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. これを解決するには、ショートカットで 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.

ビジュアル要素マニフェストのサンプル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++ショートカットを作成する方法を示しています。これには、ビジュアル要素マニフェスト 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. 注: このオーバーライドは、ショートカットがマニフェストに関連付けられている EXE を直接指していない場合にのみ必要です (例: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