Implementare utilità di avvio per app 3D (app Win32)

Articolo
07/12/2023

Nota

Questa funzionalità è disponibile solo per i PC che eseguono i voli Windows Insider più recenti (RS5), build 17704 e versioni successive.

La Windows Mixed Reality home è il punto di partenza in cui gli utenti arrivano prima di avviare le applicazioni. Per impostazione predefinita, è necessario avviare app e giochi Win32 VR immersive dall'esterno del visore VR e non verranno visualizzati nell'elenco "Tutte le app" nel menu Start Windows Mixed Reality. Se segui le istruzioni in questo articolo per implementare un'icona di avvio delle app 3D, la tua esperienza VR Win32 immersiva può essere avviata dall'interno del menu Start Windows Mixed Reality e dell'ambiente home.

Questo vale solo per le esperienze VR Win32 immersive distribuite all'esterno di Steam. Per le esperienze VR distribuite tramite Steam, abbiamo aggiornato il Windows Mixed Reality per SteamVR Beta insieme ai più recenti voli di Windows Insider RS5 in modo che i titoli SteamVR vengano visualizzati nel menu Start Windows Mixed Reality nell'elenco "Tutte le app" automaticamente usando un'icona di avvio predefinita. In altre parole, il metodo descritto in questo articolo non è necessario per i titoli SteamVR e verrà sostituito dalla Windows Mixed Reality per la funzionalità SteamVR Beta.

Processo di creazione dell'icona di avvio delle app 3D

La creazione di un'icona di avvio delle app 3D prevede tre passaggi:

Progettazione e concetti
Modellazione ed esportazione
Integrazione nell'applicazione (questo articolo)

Gli asset 3D da usare come utilità di avvio per l'applicazione devono essere creati usando le linee guida per la creazione di Windows Mixed Reality per garantire la compatibilità. Gli asset che non soddisfano questa specifica di creazione non verranno visualizzati nella home Windows Mixed Reality.

Configurazione dell'utilità di avvio 3D

Le applicazioni Win32 verranno visualizzate nell'elenco "Tutte le app" nel menu Start Windows Mixed Reality se crei un'icona di avvio delle app 3D per loro. A tale scopo, creare un file XML del manifesto di Visual Elements che fa riferimento all'utilità di avvio delle app 3D seguendo questa procedura:

Creare un file GLB dell'asset di Avvio app 3D (vedere Modellazione ed esportazione).
Creare un manifesto degli elementi visivi per l'applicazione.
1. È possibile iniziare con l'esempio seguente. Per altri dettagli, vedere la documentazione completa del manifesto di Visual Elements .
2. Aggiornare Square150x150Logo e Square70x70Logo con png/JPG/GIF per l'app.
  - Verranno usati per il logo 2D dell'app nell'elenco Windows Mixed Reality Tutte le app e per il menu Start sul desktop.
  - Il percorso del file si basa sulla cartella contenente il manifesto di Visual Elements.
  - È comunque necessario fornire un'icona del menu Start desktop per l'app tramite i meccanismi standard. Può essere direttamente nel file eseguibile o nel collegamento creato. Ad esempio, tramite IShellLink::SetIconLocation.
  - Opzionale: È possibile usare un file resources.pri se si vuole che MRT fornisca più dimensioni di asset per scale di risoluzione diverse e temi a contrasto elevato.
3. Aggiornare il percorso MixedRealityModel in modo che punti al GLB per l'icona di avvio delle app 3D
4. Salvare il file con lo stesso nome del file eseguibile, con estensione ".VisualElementsManifest.xml" e salvarlo nella stessa directory. Ad esempio, per il file eseguibile "contoso.exe", il file XML a cui si accompagna è denominato "contoso.visualelementsmanifest.xml".
Aggiungere un collegamento all'applicazione al menu Start di Windows desktop. Vedere l'esempio seguente per un'implementazione C++ di esempio.
- Crearlo in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programmi (computer) o %APPDATA%\Microsoft\Windows\Menu Start\Programmi (utente)
- Se un aggiornamento modifica il manifesto degli elementi visivi o gli asset a cui fa riferimento, l'aggiornamento o il programma di installazione deve aggiornare il collegamento in modo che il manifesto venga riparsed e gli asset memorizzati nella cache vengano aggiornati.
Opzionale: Se il collegamento desktop non punta direttamente al file EXE dell'applicazione( ad esempio, se richiama un gestore di protocolli personalizzato come "myapp://"), il menu Start non troverà automaticamente il file di VisualElementsManifest.xml dell'app. Per risolvere il problema, il collegamento deve specificare il percorso del file del manifesto degli elementi visivi usando System.AppUserModel.VisualElementsManifestHintPath (). Questa impostazione può essere impostata nel collegamento usando le stesse tecniche di System.AppUserModel.ID. Non è necessario usare System.AppUserModel.ID, ma è possibile farlo se si vuole che il collegamento corrisponda all'ID modello utente applicazione esplicito dell'applicazione, se ne viene usato uno. Per un esempio di esempio, vedere la sezione relativa alla creazione di collegamenti all'utilità di avvio delle app di seguito.

Manifesto di elementi visivi di esempio

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

Creazione di tasti di scelta rapida dell'utilità di avvio delle app di esempio

Il codice di esempio seguente mostra come creare un collegamento in C++, incluso l'override del percorso del file XML del manifesto di Visual Elements. Si noti che l'override è obbligatorio solo nei casi in cui il collegamento non punta direttamente al file EXE associato al manifesto( ad esempio, il collegamento usa un gestore di protocollo personalizzato come "myapp://").

Esempio. Creazione del collegamento 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;
}

Esempio. Collegamento all'utilità di avvio 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

Vedi anche

Esempio di modello di realtà mista contenente un'icona di avvio delle app 3D.
Linee guida per la progettazione di utilità di avvio di app 3D
Creazione di modelli 3D da usare nella home page di Windows Mixed Reality
Implementazione di utilità di avvio delle app 3D (app UWP)
Esplorazione dello spazio iniziale di Windows Mixed Reality

Condividi tramite