Implementowanie uruchamiania aplikacji 3D (aplikacje Win32)

Artykuł
07/12/2023

Uwaga

Ta funkcja jest dostępna tylko dla komputerów z najnowszymi testami testów systemu Windows (RS5), kompilacją 17704 i nowszymi.

Windows Mixed Reality domu jest punktem wyjścia, w którym użytkownicy lądują przed uruchomieniem aplikacji. Domyślnie należy uruchomić immersyjne aplikacje i gry Win32 VR spoza zestawu słuchawkowego i nie będą wyświetlane na liście "Wszystkie aplikacje" w menu Start Windows Mixed Reality. Jeśli wykonasz instrukcje opisane w tym artykule, aby zaimplementować uruchamianie aplikacji 3D, środowisko immersywne Win32 VR można uruchomić z poziomu menu Windows Mixed Reality Start i środowiska domowego.

Dotyczy to tylko immersywnych środowisk Win32 VR dystrybuowanych poza Steam. W przypadku środowisk VR dystrybuowanych przez Steam zaktualizowaliśmy Windows Mixed Reality dla SteamVR Beta wraz z najnowszymi lotami Windows Insider RS5, tak aby tytuły SteamVR były wyświetlane w menu Start Windows Mixed Reality na liście "Wszystkie aplikacje" automatycznie przy użyciu domyślnego uruchamiania. Innymi słowy, metoda opisana w tym artykule jest niepotrzebna dla tytułów SteamVR i zostanie zastąpiona przez Windows Mixed Reality dla funkcji SteamVR Beta.

Proces tworzenia modułu uruchamiania aplikacji 3D

Tworzenie modułu uruchamiania aplikacji 3D obejmuje trzy kroki:

Projektowanie i koncepcje
Modelowanie i eksportowanie
Integrowanie jej z aplikacją (ten artykuł)

Zasoby 3D, które mają być używane jako moduły uruchamiające dla aplikacji, powinny być tworzone przy użyciu wytycznych dotyczących tworzenia Windows Mixed Reality w celu zapewnienia zgodności. Zasoby, które nie spełniają tej specyfikacji tworzenia, nie będą renderowane w Windows Mixed Reality domu.

Konfigurowanie uruchamiania 3D

Aplikacje Win32 będą wyświetlane na liście "Wszystkie aplikacje" w menu Start Windows Mixed Reality, jeśli utworzysz dla nich uruchamianie aplikacji 3D. W tym celu utwórz plik XML manifestu elementów wizualnych odwołujących się do uruchamiania aplikacji 3D, wykonując następujące kroki:

Tworzenie pliku GLB elementu zawartości uruchamiania aplikacji 3D (zobacz Modelowanie i eksportowanie).
Utwórz manifest elementów wizualnych dla aplikacji.
1. Możesz rozpocząć od poniższego przykładu. Aby uzyskać więcej informacji, zobacz pełną dokumentację manifestu elementów wizualnych .
2. Zaktualizuj square150x150Logo i Square70x70Logo za pomocą png/JPG/GIF dla aplikacji.
  - Będą one używane na potrzeby logo 2D aplikacji na liście Windows Mixed Reality Wszystkie aplikacje i menu Start na pulpicie.
  - Ścieżka pliku jest oparta na folderze zawierającym manifest elementów wizualnych.
  - Nadal musisz podać ikonę menu Start pulpitu dla aplikacji za pomocą standardowych mechanizmów. Może to być bezpośrednio w pliku wykonywalny lub w utworzonym skrótie. Na przykład za pośrednictwem interfejsu IShellLink::SetIconLocation.
  - Opcjonalne: Możesz użyć pliku resources.pri, jeśli chcesz, aby zestaw NARZĘDZI MRT zapewniał wiele rozmiarów zasobów dla różnych skalowania rozdzielczości i motywów o wysokim kontraście.
3. Zaktualizuj ścieżkę MixedRealityModel , aby wskazywała usługę GLB dla modułu uruchamiania aplikacji 3D
4. Zapisz plik o tej samej nazwie co plik wykonywalny z rozszerzeniem ".VisualElementsManifest.xml" i zapisz go w tym samym katalogu. Na przykład w przypadku pliku wykonywalnego "contoso.exe" towarzyszący plik XML nosi nazwę "contoso.visualelementsmanifest.xml".
Dodaj skrót do aplikacji do pulpitu Menu Start systemu Windows. Zapoznaj się z poniższym przykładem implementacji języka C++.
- Utwórz go w folderze %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (maszyna) lub %APPDATA%\Microsoft\Windows\Start Menu\Programs (użytkownik)
- Jeśli aktualizacja zmienia manifest elementów wizualizacji lub przywoływane przez nią zasoby, aktualizator lub instalator powinien zaktualizować skrót, tak aby manifest został ponownie utworzony i zaktualizowany w pamięci podręcznej.
Opcjonalne: Jeśli skrót na pulpicie nie wskazuje bezpośrednio na plik EXE aplikacji (na przykład jeśli wywołuje niestandardowy program obsługi protokołu, taki jak "myapp://"), menu Start nie będzie automatycznie znajdować pliku VisualElementsManifest.xml aplikacji. Aby rozwiązać ten problem, skrót powinien określać ścieżkę pliku manifestu elementów wizualnych przy użyciu elementu System.AppUserModel.VisualElementsManifestHintPath (). Można to ustawić w skrótach przy użyciu tych samych technik, co System.AppUserModel.ID. Nie musisz używać System.AppUserModel.ID, ale możesz to zrobić, jeśli chcesz, aby skrót był zgodny z jawnym identyfikatorem modelu użytkownika aplikacji, jeśli jest używany. Zobacz sekcję tworzenia skrótów do uruchamiania aplikacji przykładowych poniżej, aby zapoznać się z przykładem języka C++.

Przykładowy manifest elementów wizualnych

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

Tworzenie skrótu do uruchamiania przykładowej aplikacji

Poniższy przykładowy kod przedstawia sposób tworzenia skrótu w języku C++, w tym zastępowania ścieżki do pliku XML manifestu elementów wizualizacji. Pamiętaj, że przesłonięcia są wymagane tylko w przypadkach, gdy skrót nie wskazuje bezpośrednio pliku EXE skojarzonego z manifestem (na przykład skrót używa niestandardowego programu obsługi protokołu, takiego jak "myapp://").

Przykładowe. Tworzenie skrótów 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;
}

Przykładowe. Skrót uruchamiania adresu 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

Udostępnij za pośrednictwem