Implementación de iniciadores de aplicaciones 3D (aplicaciones Win32)Implement 3D app launchers (Win32 apps)

Nota

Esta característica solo está disponible para los equipos que ejecutan la versión más reciente de Windows Insider (RS5), compilación 17704 y versiones más recientes.This feature is only available to PCs running the latest Windows Insider flights (RS5), build 17704 and newer.

La Página principal de Windows Mixed Reality es el punto de partida en el que los usuarios se colocan antes de iniciar las aplicaciones.The Windows Mixed Reality home is the starting point where users land before launching applications. De forma predeterminada, debe iniciar aplicaciones y juegos de Win32 VR envolventes desde fuera del casco y no aparecerán en la lista "todas las aplicaciones" del menú Inicio de Windows Mixed Reality.By default, you need to launch immersive Win32 VR apps and games from outside the headset and won't appear in the "All apps" list on the Windows Mixed Reality Start menu. Si sigue las instrucciones de este artículo para implementar un iniciador de aplicaciones 3D, su experiencia de Win32 VR envolvente se puede iniciar desde el menú Inicio de Windows Mixed Reality y el entorno de inicio.If you follow the instructions in this article to implement a 3D app launcher, your immersive Win32 VR experience can be launched from within the Windows Mixed Reality Start menu and home environment.

Esto solo es válido para las experiencias de Win32 VR envolventes distribuidas fuera de la secuencia.This is only true for immersive Win32 VR experiences distributed outside of Steam. En el caso de las experiencias de VR distribuidas a través de vapor, hemos actualizado Windows Mixed Reality para SteamVR beta junto con los vuelos de Windows Insider RS5 más recientes para que los títulos de SteamVR aparezcan en el menú Inicio de Windows Mixed Reality en la lista "todas las aplicaciones" automáticamente mediante un iniciador predeterminado.For VR experiences distributed through Steam, we've updated the Windows Mixed Reality for SteamVR Beta along with the latest Windows Insider RS5 flights so that SteamVR titles show up in the Windows Mixed Reality Start menu in the "All apps" list automatically using a default launcher. En otras palabras, el método descrito en este artículo no es necesario para los títulos de SteamVR y se reemplazará por la funcionalidad de Windows Mixed Reality para SteamVR beta.In other words, the method described in this article is unnecessary for SteamVR titles and will be overridden by the Windows Mixed Reality for SteamVR Beta functionality.

proceso de creación del iniciador de aplicaciones 3D3D app launcher creation process

Hay tres pasos para crear un iniciador de aplicaciones 3D:There are three steps to creating a 3D app launcher:

  1. Diseño y conceptoDesigning and concepting
  2. Modelado y exportaciónModeling and exporting
  3. Integrarlo en la aplicación (este artículo)Integrating it into your application (this article)

los recursos 3D que se usarán como iniciadores de la aplicación deben crearse con las directrices de creación de Windows Mixed Reality para garantizar la compatibilidad.3D assets to be used as launchers for your application should be authored using the Windows Mixed Reality authoring guidelines to ensure compatibility. Los recursos que no cumplan esta especificación de creación no se representarán en la Página principal de Windows Mixed Reality.Assets that fail to meet this authoring specification won't be rendered in the Windows Mixed Reality home.

Configurar el iniciador 3DConfiguring the 3D launcher

Las aplicaciones Win32 aparecerán en la lista "todas las aplicaciones" del menú Inicio de Windows Mixed Reality si crea un selector de aplicaciones 3D para ellas.Win32 applications will appear in the "All apps" list on the Windows Mixed Reality Start menu if you create a 3D app launcher for them. Para ello, cree un archivo XML de manifiesto de elementos visuales que haga referencia al iniciador de aplicaciones 3D siguiendo estos pasos:To do that, create a Visual Elements Manifest XML file referencing the 3D App Launcher by following these steps:

  1. Cree un archivo glb de activo del iniciador de aplicaciones 3D (consulte modelado y exportación).Create a 3D App Launcher asset GLB file (See Modeling and exporting).
  2. Cree un manifiesto de elementos visuales para la aplicación.Create a Visual Elements Manifest for your application.
    1. Puede empezar con el ejemplo siguiente.You can start with the sample below. Consulte la documentación del manifiesto de elementos visuales completos para obtener más detalles.See the full Visual Elements Manifest documentation for more details.
    2. Actualice Square150x150Logo y Square70x70Logo con un archivo PNG/JPG/GIF para la aplicación.Update Square150x150Logo and Square70x70Logo with a PNG/JPG/GIF for your app.
      • Se usarán para el logotipo de 2D de la aplicación en la lista todas las aplicaciones de Windows Mixed Reality y para el menú Inicio en el escritorio.These will be used for the app’s 2D logo in the Windows Mixed Reality All Apps list and for the Start Menu on desktop.
      • La ruta de acceso del archivo se basa en la carpeta que contiene el manifiesto de elementos visuales.The file path is based on the folder containing the Visual Elements Manifest.
      • Todavía tiene que proporcionar un icono de menú Inicio de escritorio para la aplicación a través de los mecanismos estándar.You still need to provide a desktop Start Menu icon for your app through the standard mechanisms. Puede estar directamente en el archivo ejecutable o en el acceso directo que cree.This can either be directly in the executable or in the shortcut you create. Por ejemplo, a través de IShellLink:: SetIconLocation.For example, via IShellLink::SetIconLocation.
      • Opcional: Puede usar un archivo resources. PRI si desea que MRT proporcione varios tamaños de recursos para diferentes escalas de resolución y temas de contraste alto.Optional: You can use a resources.pri file if you would like for MRT to provide multiple asset sizes for different resolution scales and high contrast themes.
    3. Actualice la ruta de acceso de MixedRealityModel para que apunte al glb del iniciador de la aplicación 3D.Update the MixedRealityModel Path to point to the GLB for your 3D App Launcher
    4. Guarde el archivo con el mismo nombre que el archivo ejecutable, con la extensión ".VisualElementsManifest.xml" y guárdelo en el mismo directorio.Save the file with the same name as your executable file, with an extension of ".VisualElementsManifest.xml" and save it in the same directory. Por ejemplo, para el archivo ejecutable "contoso.exe", el archivo XML que lo acompaña se denomina "contoso.visualelementsmanifest.xml".For example, for the executable file "contoso.exe", the accompanying XML file is named "contoso.visualelementsmanifest.xml".
  3. Agregue un acceso directo a la aplicación en el menú Inicio de Windows de escritorio.Add a shortcut to your application to the desktop Windows Start Menu. Vea el ejemplo siguiente para obtener una implementación de C++ de ejemplo.See the sample below for an example C++ implementation.
    • Créelo en%ALLUSERSPROFILE%\Microsoft\Windows\Start Inicio\programas (equipo) o en el Inicio\programas de%APPDATA%\Microsoft\Windows\Start (usuario)Create it in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (machine) or %APPDATA%\Microsoft\Windows\Start Menu\Programs (user)
    • Si una actualización cambia el manifiesto de los elementos visuales o los recursos a los que hace referencia, el instalador o actualizador debe actualizar el acceso directo para que el manifiesto se analice y se actualicen los recursos almacenados en caché.If an update changes your visual elements manifest or the assets referenced by it, the updater or installer should update the shortcut such that the manifest is reparsed and cached assets are updated.
  4. Opcional: Si el acceso directo del escritorio no apunta directamente al archivo EXE de la aplicación (por ejemplo, si invoca un controlador de protocolo personalizado como "myapp://"), el menú Inicio no buscará automáticamente el archivo de VisualElementsManifest.xml de la aplicación.Optional: If your desktop shortcut doesn't point directly to your application’s EXE (for example, if it invokes a custom protocol handler like “myapp://”), the Start Menu won’t automatically find the app’s VisualElementsManifest.xml file. Para resolverlo, el acceso directo debe especificar la ruta de acceso del archivo del manifiesto de elementos visuales con System. AppUserModel. VisualElementsManifestHintPath ().To resolve this, the shortcut should specify the file path of the Visual Elements Manifest using System.AppUserModel.VisualElementsManifestHintPath (). Se puede establecer en el acceso directo con las mismas técnicas que System.AppUserModel.ID.This can be set in the shortcut using the same techniques as System.AppUserModel.ID. No es necesario usar System.AppUserModel.ID, pero puede hacerlo si desea que el acceso directo coincida con el identificador de modelo de usuario de aplicación explícito de la aplicación si se usa uno.You aren't required to use System.AppUserModel.ID but you may do so if you wish for the shortcut to match the explicit Application User Model ID of the application if one is used. Vea la sección creación de acceso directo del iniciador de aplicaciones de ejemplo siguiente para obtener un ejemplo de C++.See the sample app launcher shortcut creation section below for a C++ sample.

Manifiesto de elementos visuales de ejemploSample Visual Elements Manifest

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

Creación de un acceso directo del iniciador de aplicaciones de ejemploSample app launcher shortcut creation

En el código de ejemplo siguiente se muestra cómo se puede crear un acceso directo en C++, incluida la invalidación de la ruta de acceso al archivo XML de manifiesto de los elementos visuales.The sample code below shows how you can create a shortcut in C++, including overriding the path to the Visual Elements Manifest XML file. Tenga en cuenta que la invalidación solo es necesaria en los casos en los que el acceso directo no apunta directamente al archivo EXE asociado al manifiesto (por ejemplo, el acceso directo usa un controlador de protocolo personalizado como "myapp://").Note the override is only required in cases where your shortcut doesn't point directly to the EXE associated with the manifest (for example, your shortcut uses a custom protocol handler like "myapp://").

AdventureWorks. Creación de accesos directos de LNK (C++)Sample .LNK shortcut creation (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;
}

AdventureWorks. Acceso directo del iniciador de URLSample .URL launcher shortcut

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

Consulte tambiénSee also