Implementieren von 3D-App-Startprogrammen (Win32-Apps)

Hinweis

Dieses Feature ist nur für PCs verfügbar, auf denen die neuesten Windows Insider Flights (RS5), Build 17704 und höher, ausgeführt werden.

Die Windows Mixed Reality Home ist der Ausgangspunkt, an dem Benutzer vor dem Starten von Anwendungen landen. Standardmäßig müssen Sie immersive Win32 VR-Apps und -Spiele außerhalb des Headsets starten und werden nicht in der Liste "Alle Apps" im Windows Mixed Reality Startmenü angezeigt. Wenn Sie die Anweisungen in diesem Artikel befolgen, um ein 3D-App-Startfeld zu implementieren, kann Ihre immersive Win32 VR-Erfahrung über das Windows Mixed Reality Startmenü und die Heimumgebung gestartet werden.

Dies gilt nur für immersive Win32 VR-Umgebungen, die außerhalb von Steam verteilt werden. Für VR-Umgebungen, die über Steam verteilt werden, haben wir die Windows Mixed Reality für SteamVR Beta zusammen mit den neuesten Windows Insider RS5-Flügen aktualisiert, sodass SteamVR-Titel im Windows Mixed Reality Startmenü in der Liste "Alle Apps" automatisch mithilfe eines Standardstartprogramms angezeigt werden. Anders ausgedrückt: Die in diesem Artikel beschriebene Methode ist für SteamVR-Titel unnötig und wird von der Windows Mixed Reality für SteamVR Beta-Funktionalität überschrieben.

Erstellungsprozess für 3D-App-Startfeld

Es gibt drei Schritte zum Erstellen eines 3D-App-Startfelds:

1. Entwerfen und Entwerfen
2. Modellieren und Exportieren
3. Integrieren in Ihre Anwendung (dieser Artikel)

3D-Ressourcen, die als Startprogramme für Ihre Anwendung verwendet werden sollen, sollten mithilfe der richtlinien für die Windows Mixed Reality-Erstellung erstellt werden, um die Kompatibilität sicherzustellen. Ressourcen, die diese Erstellungsspezifikation nicht erfüllen, werden im Windows Mixed Reality Home nicht gerendert.

Konfigurieren des 3D-Startprogramms

Win32-Anwendungen werden in der Liste "Alle Apps" im Windows Mixed Reality Startmenü angezeigt, wenn Sie ein 3D-App-Startfeld für sie erstellen. Erstellen Sie hierzu eine XML-Datei des Visual Elements-Manifests , die auf das 3D-App-Startfeld verweist, indem Sie die folgenden Schritte ausführen:

1. Erstellen Sie eine GLB-Datei für das 3D-App-Startprogramm (siehe Modellieren und Exportieren).
2. Erstellen Sie ein Visual Elements-Manifest für Ihre Anwendung.
   1. Sie können mit dem folgenden Beispiel beginnen. Weitere Informationen finden Sie in der vollständigen Dokumentation zum Visual Elements-Manifest .
   2. Aktualisieren Sie Square150x150Logo und Square70x70Logo mit einem PNG/JPG/GIF für Ihre App.
      • Diese werden für das 2D-Logo der App in der Liste Windows Mixed Reality Alle Apps und für das Startmenü auf dem Desktop verwendet.
      • Der Dateipfad basiert auf dem Ordner, der das Visual Elements-Manifest enthält.
      • Sie müssen weiterhin ein Desktop-Startmenüsymbol für Ihre App über die Standardmechanismen bereitstellen. Dies kann sich entweder direkt in der ausführbaren Datei oder in der von Ihnen erstellten Verknüpfung befinden. Beispielsweise über IShellLink::SetIconLocation.
      • Optional: Sie können eine resources.pri-Datei verwenden, wenn Sie möchten, dass MRT mehrere Ressourcengrößen für verschiedene Auflösungsskalen und Designs mit hohem Kontrast bereitstellen soll.
   3. Aktualisieren Sie den MixedRealityModel-Pfad , um auf den GLB für Ihr 3D-App-Startfeld zu verweisen.
   4. Speichern Sie die Datei mit demselben Namen wie Ihre ausführbare Datei, mit der Erweiterung ".VisualElementsManifest.xml", und speichern Sie sie im selben Verzeichnis. Für die ausführbare Datei "contoso.exe" hat die begleitende XML-Datei den Namen "contoso.visualelementsmanifest.xml".
3. Fügen Sie ihrer Anwendung eine Verknüpfung zum Windows-Startmenü auf dem Desktop hinzu. Im folgenden Beispiel finden Sie ein Beispiel für eine C++-Implementierung.
   • Erstellen Sie es in %ALLUSERSPROFILE%\Microsoft\Windows\Startmenü\Programme (Computer) oder %APPDATA%\Microsoft\Windows\Startmenü\Programme (Benutzer)
   • Wenn ein Update Das Manifest für visuelle Elemente oder die objekte, auf die verwiesen wird, ändert, sollte der Updater oder Installer die Verknüpfung so aktualisieren, dass das Manifest analysiert und zwischengespeicherte Ressourcen aktualisiert werden.
4. Optional: Wenn Ihre Desktopverknüpfung nicht direkt auf das EXE Ihrer Anwendung verweist (wenn sie z. B. einen benutzerdefinierten Protokollhandler wie "myapp://" aufruft), findet das Startmenü nicht automatisch die VisualElementsManifest.xml Datei der App. Um dies zu beheben, sollte die Verknüpfung den Dateipfad des Visual Elements-Manifests mithilfe von System.AppUserModel.VisualElementsManifestHintPath () angeben. Dies kann in der Verknüpfung mithilfe der gleichen Techniken wie System.AppUserModel.ID festgelegt werden. Es ist nicht erforderlich, System.AppUserModel.ID zu verwenden, aber Sie können dies tun, wenn Sie möchten, dass die Verknüpfung mit der expliziten Anwendungsbenutzermodell-ID der Anwendung übereinstimmt, sofern eine verwendet wird. Ein C++-Beispiel finden Sie weiter unten im Abschnitt zum Erstellen von Tastenkombinationen für das App-Startfeld .

Beispielmanifest für visuelle Elemente

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

Erstellen einer Beispiel-App-Startprogrammverknüpfung

Der folgende Beispielcode zeigt, wie Sie eine Verknüpfung in C++ erstellen können, einschließlich des Überschreibens des Pfads zur Visual Elements-Manifest-XML-Datei. Beachten Sie, dass die Außerkraftsetzung nur in Fällen erforderlich ist, in denen Die Verknüpfung nicht direkt auf die EXE zeigt, die dem Manifest zugeordnet ist (z. B. verwendet Ihre Verknüpfung einen benutzerdefinierten Protokollhandler wie "myapp://").

Beispiel. Erstellen von LNK-Verknüpfungen (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;
}

Beispiel. URL-Startprogrammverknüpfung

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

Weitere Informationen

• Mixed Reality-Modellbeispiel mit einem 3D-App-Startfeld.
• Entwurfsanleitung für 3D-App-Startprogramm
• Erstellen von 3D-Modellen für die Verwendung im Windows Mixed Reality Home
• Implementieren von 3D-App-Startprogrammen (UWP-Apps)
• Navigieren auf der Startseite von Windows Mixed Reality