Implémenter des lanceurs d’applications 3D (applications Win32)

  • Article

Notes

Cette fonctionnalité est uniquement disponible pour les PC exécutant les dernières versions d’évaluation Windows Insider (RS5), build 17704 et versions ultérieures.

Le Windows Mixed Reality domicile est le point de départ où les utilisateurs atterrissent avant de lancer des applications. Par défaut, vous devez lancer des applications et des jeux win32 VR immersifs à partir de l’extérieur du casque et n’apparaît pas dans la liste « Toutes les applications » du menu Démarrer Windows Mixed Reality. Si vous suivez les instructions de cet article pour implémenter un lanceur d’applications 3D, votre expérience immersive Win32 VR peut être lancée à partir du menu Démarrer Windows Mixed Reality et de l’environnement d’accueil.

Cela est uniquement vrai pour les expériences immersives Win32 VR distribuées en dehors de Steam. Pour les expériences de réalité virtuelle distribuées via Steam, nous avons mis à jour les Windows Mixed Reality pour SteamVR Beta ainsi que les derniers vols Windows Insider RS5 afin que les titres SteamVR s’affichent automatiquement dans le menu Démarrer Windows Mixed Reality de la liste « Toutes les applications » à l’aide d’un lanceur par défaut. En d’autres termes, la méthode décrite dans cet article n’est pas nécessaire pour les titres SteamVR et sera remplacée par la fonctionnalité Windows Mixed Reality pour SteamVR Beta.

Processus de création du lanceur d’applications 3D

Il existe trois étapes pour créer un lanceur d’applications 3D :

  1. Conception et conception
  2. Modélisation et exportation
  3. Intégration à votre application (cet article)

Les ressources 3D à utiliser comme lanceurs pour votre application doivent être créées à l’aide des instructions de création Windows Mixed Reality pour garantir la compatibilité. Les ressources qui ne répondent pas à cette spécification de création ne seront pas affichées dans le Windows Mixed Reality accueil.

Configuration du lanceur 3D

Les applications Win32 s’affichent dans la liste « Toutes les applications » du menu Démarrer Windows Mixed Reality si vous créez un lanceur d’applications 3D pour elles. Pour ce faire, créez un fichier XML manifeste Visual Elements référençant le lanceur d’applications 3D en procédant comme suit :

  1. Créez un fichier GLB de ressource du lanceur d’applications 3D (consultez Modélisation et exportation).
  2. Créez un manifeste d’éléments visuels pour votre application.
    1. Vous pouvez commencer par l’exemple ci-dessous. Pour plus d’informations, consultez la documentation complète du manifeste Visual Elements .
    2. Mettez à jour Square150x150Logo et Square70x70Logo avec un PNG/JPG/GIF pour votre application.
      • Ils seront utilisés pour le logo 2D de l’application dans la liste Windows Mixed Reality Toutes les applications et pour le menu Démarrer sur le bureau.
      • Le chemin d’accès au fichier est basé sur le dossier contenant le manifeste des éléments visuels.
      • Vous devez toujours fournir une icône de menu Démarrer du bureau pour votre application via les mécanismes standard. Cela peut être directement dans l’exécutable ou dans le raccourci que vous créez. Par exemple, via IShellLink::SetIconLocation.
      • Optionnel: Vous pouvez utiliser un fichier resources.pri si vous souhaitez que MRT fournisse plusieurs tailles de ressources pour différentes échelles de résolution et thèmes à contraste élevé.
    3. Mettez à jour le chemin MixedRealityModel pour qu’il pointe vers le GLB pour votre lanceur d’applications 3D
    4. Enregistrez le fichier avec le même nom que votre fichier exécutable, avec l’extension « .VisualElementsManifest.xml » et enregistrez-le dans le même répertoire. Par exemple, pour le fichier exécutable « contoso.exe », le fichier XML associé est nommé « contoso.visualelementsmanifest.xml ».
  3. Ajoutez un raccourci à votre application dans le menu Démarrer de Windows de bureau. Consultez l’exemple ci-dessous pour obtenir un exemple d’implémentation C++.
    • Créez-le dans %ALLUSERSPROFILE%\Microsoft\Windows\Menu Démarrer\Programs (machine) ou %APPDATA%\Microsoft\Windows\Start Menu\Programs (utilisateur)
    • Si une mise à jour modifie votre manifeste d’éléments visuels ou les ressources référencées par elle, le programme d’installation ou de mise à jour doit mettre à jour le raccourci de sorte que le manifeste soit réécrit et que les ressources mises en cache soient mises à jour.
  4. Optionnel: Si votre raccourci de bureau ne pointe pas directement vers l’exe de votre application (par exemple, s’il appelle un gestionnaire de protocole personnalisé comme « myapp:// »), le menu Démarrer ne trouve pas automatiquement le fichier VisualElementsManifest.xml de l’application. Pour résoudre ce problème, le raccourci doit spécifier le chemin du fichier du manifeste Visual Elements à l’aide de System.AppUserModel.VisualElementsManifestHintPath (). Cela peut être défini dans le raccourci à l’aide des mêmes techniques que System.AppUserModel.ID. Vous n’êtes pas obligé d’utiliser System.AppUserModel.ID, mais vous pouvez le faire si vous souhaitez que le raccourci corresponde à l’ID de modèle utilisateur d’application explicite de l’application, le cas échéant. Consultez la section création d’un exemple de raccourci de lanceur d’applications ci-dessous pour obtenir un exemple C++.

Exemple de manifeste d’éléments visuels

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

Exemple de création de raccourci de lanceur d’applications

L’exemple de code ci-dessous montre comment créer un raccourci en C++, notamment en remplaçant le chemin d’accès au fichier MANIFESTE XML visual Elements. Notez que le remplacement est nécessaire uniquement dans les cas où votre raccourci ne pointe pas directement vers l’EXE associé au manifeste (par exemple, votre raccourci utilise un gestionnaire de protocole personnalisé comme « myapp:// »).

Échantillon. Création de raccourcis 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;
}

Échantillon. Raccourci du lanceur d’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

Voir aussi