3D 앱 시작 관리자(Win32 앱) 구현Implement 3D app launchers (Win32 apps)

참고

이 기능은 최신 Windows 참가자 항공편 (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, you need to launch immersive Win32 VR apps and games 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 환경을 시작할 수 있습니다.If you follow 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 환경에만 적용 됩니다.This is only true for immersive Win32 VR experiences distributed outside of Steam. 스트림를 통해 배포되는 VR 환경의 경우 SteamVR Beta에 대 한 windows mixed Reality 를 최신 windows 참가자 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 제목에는 필요 하지 않으며 SteamVR Beta 기능을 위해 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 앱 시작 관리자를 만드는 세 가지 단계가 있습니다.There are three 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 won't be rendered in the Windows Mixed Reality home.

3D 시작 관리자 구성Configuring the 3D launcher

Win32 응용 프로그램은 3D 앱 시작 관리자를 만드는 경우 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. 이렇게 하려면 다음 단계를 수행 하 여 3D 앱 시작 관리자를 참조 하는 시각적 요소 매니페스트 XML 파일을 만듭니다.To do that, create a Visual Elements Manifest XML file referencing the 3D App Launcher by following these steps:

  1. 3D 앱 시작 관리자 자산 및 파일 만들기 ( 모델링 및 내보내기참조)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. 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 based on the folder containing the Visual Elements Manifest.
      • 표준 메커니즘을 통해 앱에 대 한 바탕 화면 시작 메뉴 아이콘을 계속 제공 해야 합니다.You still need to provide a desktop Start Menu icon for your app through the standard mechanisms. 이 파일은 실행 파일 또는 사용자가 만드는 바로 가기에서 직접 지정할 수 있습니다.This can either be directly in the executable or in the shortcut you create. 예: IShellLink:: SetIconLocation을 통해.For example, via IShellLink::SetIconLocation.
      • 선택 사항: MRT.LOG에서 다양 한 해상도 크기 조정 및 고대비 테마에 대 한 여러 자산 크기를 제공 하려는 경우에는 리소스 .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 앱 시작 관리자에 대 한 지 수 b를 가리키도록 MixedRealityModel 경로 를 업데이트 합니다.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 (machine) 또는%APPDATA%\Microsoft\Windows\Start Menu\Programs (사용자)에 만듭니다.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. 선택 사항: 바탕 화면 바로 가기가 응용 프로그램의 EXE를 직접 가리키지 않는 경우 (예: "myapp://"와 같은 사용자 지정 프로토콜 처리기를 호출 하는 경우) 시작 메뉴에서 앱의 VisualElementsManifest.xml 파일을 자동으로 찾을 수 없습니다.Optional: If your desktop shortcut doesn't point directly to your application’s EXE (for example, 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 aren't 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="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>

샘플 앱 시작 관리자 바로 가기 만들기Sample app launcher shortcut creation

아래 샘플 코드에서는 시각적 요소 매니페스트 XML 파일에 대 한 경로 재정의를 비롯 하 여 c + +에서 바로 가기를 만드는 방법을 보여 줍니다.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를 직접 가리키지 않는 경우에만 필요 합니다. 예를 들어 바로 가기에서 "myapp://"와 같은 사용자 지정 프로토콜 처리기를 사용 합니다.Note the override is only required in cases where your shortcut doesn't point directly to the EXE associated with the manifest (for example, 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