Startprogramma's voor 3D-apps implementeren (Win32-apps)

Notitie

Deze functie is alleen beschikbaar voor pc's met de nieuwste Windows Insider-vluchten (RS5), build 17704 en hoger.

De Windows Mixed Reality home is het beginpunt waar gebruikers terechtkomen voordat ze toepassingen starten. Standaard moet u insluitende Win32 VR-apps en -games starten van buiten de headset. Deze worden niet weergegeven in de lijst 'Alle apps' in het menu Start Windows Mixed Reality. Als u de instructies in dit artikel volgt om een startprogramma voor 3D-apps te implementeren, kunt u uw insluitende Win32 VR-ervaring starten vanuit het Windows Mixed Reality startmenu en de thuisomgeving.

Dit geldt alleen voor meeslepende Win32 VR-ervaringen die buiten Steam worden gedistribueerd. Voor VR-ervaringen die via Steam worden gedistribueerd, hebben we de Windows Mixed Reality voor SteamVR Beta samen met de nieuwste Windows Insider RS5-vluchten bijgewerkt, zodat SteamVR-titels automatisch worden weergegeven in het menu Start van Windows Mixed Reality in de lijst 'Alle apps' met behulp van een standaardstartprogramma. Met andere woorden, de methode die in dit artikel wordt beschreven, is niet nodig voor SteamVR-titels en wordt overschreven door de Windows Mixed Reality voor steamVR Beta-functionaliteit.

Proces voor het maken van het startprogramma voor 3D-apps

Er zijn drie stappen voor het maken van een 3D-startprogramma voor apps:

  1. Ontwerpen en concepteren
  2. Modelleren en exporteren
  3. Deze integreren in uw toepassing (dit artikel)

3D-assets die moeten worden gebruikt als startprogramma's voor uw toepassing, moeten worden gemaakt met behulp van de Windows Mixed Reality ontwerprichtlijnen om compatibiliteit te garanderen. Assets die niet aan deze ontwerpspecificatie voldoen, worden niet weergegeven in de Windows Mixed Reality home.

Het 3D-startprogramma configureren

Win32-toepassingen worden weergegeven in de lijst 'Alle apps' in het menu Start Windows Mixed Reality als u een 3D-startprogramma voor apps maakt. Hiervoor maakt u een Visual Elements Manifest XML-bestand dat verwijst naar het startprogramma voor 3D-apps door de volgende stappen uit te voeren:

  1. Maak een 3D App Launcher-asset GLB-bestand (zie Modelleren en exporteren).
  2. Maak een Visual Elements Manifest voor uw toepassing.
    1. U kunt beginnen met het onderstaande voorbeeld. Zie de volledige visual elements manifest documentatie voor meer informatie.
    2. Werk Square150x150Logo en Square70x70Logo bij met een PNG/JPG/GIF voor uw app.
      • Deze worden gebruikt voor het 2D-logo van de app in de lijst Windows Mixed Reality Alle apps en voor het startmenu op het bureaublad.
      • Het bestandspad is gebaseerd op de map die het Visual Elements Manifest bevat.
      • U moet nog steeds een pictogram van het startmenu op het bureaublad opgeven voor uw app via de standaardmechanismen. Dit kan rechtstreeks in het uitvoerbare bestand staan of in de snelkoppeling die u maakt. Bijvoorbeeld via IShellLink::SetIconLocation.
      • Optionele: U kunt een resources.pri-bestand gebruiken als u wilt dat MRT meerdere assetgrootten biedt voor verschillende resolutieschalen en thema's met hoog contrast.
    3. Werk het pad MixedRealityModel bij zodat deze verwijst naar het GLB voor het startprogramma voor 3D-apps
    4. Sla het bestand op met dezelfde naam als het uitvoerbare bestand, met de extensie '.VisualElementsManifest.xml' en sla het op in dezelfde map. Voor het uitvoerbare bestand 'contoso.exe' heeft het bijbehorende XML-bestand bijvoorbeeld de naam 'contoso.visualelementsmanifest.xml'.
  3. Voeg een snelkoppeling naar uw toepassing toe aan het bureaubladmenu Start van Windows. Zie het onderstaande voorbeeld voor een voorbeeld van een C++-implementatie.
    • Maak het in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (machine) of %APPDATA%\Microsoft\Windows\Start Menu\Programs (gebruiker)
    • Als een update het manifest van visuele elementen of de assets waarnaar wordt verwezen, wijzigt, moet het updateprogramma of het installatieprogramma de snelkoppeling zodanig bijwerken dat het manifest opnieuw wordt geparseerd en assets in de cache worden bijgewerkt.
  4. Optionele: Als de snelkoppeling op het bureaublad niet rechtstreeks naar de EXE van uw toepassing verwijst (bijvoorbeeld als deze een aangepaste protocolhandler aanroept, zoals 'myapp://'), wordt het VisualElementsManifest.xml-bestand van de app niet automatisch gevonden. U kunt dit oplossen door met de snelkoppeling het bestandspad van het Visual Elements-manifest op te geven met behulp van System.AppUserModel.VisualElementsManifestHintPath (). Dit kan worden ingesteld in de snelkoppeling met behulp van dezelfde technieken als System.AppUserModel.ID. U bent niet verplicht om System.AppUserModel.ID te gebruiken, maar u kunt dit doen als u wilt dat de snelkoppeling overeenkomt met de expliciete toepassingsgebruikersmodel-id van de toepassing als deze wordt gebruikt. Zie de sectie voor het maken van snelkoppelingen voor het starten van apps hieronder voor een C++-voorbeeld.

Voorbeeldmanifest voor visuele elementen

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

Voorbeeldsnelkoppeling maken van startprogramma voor apps

In de onderstaande voorbeeldcode ziet u hoe u een snelkoppeling kunt maken in C++, inclusief het overschrijven van het pad naar het Visual Elements Manifest XML-bestand. Opmerking: de onderdrukking is alleen vereist in gevallen waarin uw snelkoppeling niet rechtstreeks verwijst naar de EXE die is gekoppeld aan het manifest (uw snelkoppeling gebruikt bijvoorbeeld een aangepaste protocolhandler zoals 'myapp://').

Monster. LNK-snelkoppeling maken (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;
}

Monster. Snelkoppeling url-startprogramma

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

Zie ook