Compartir a través de

Implementación de iniciadores de aplicaciones 3D (aplicaciones Win32)

  • Artículo

Nota:

Esta característica solo está disponible para equipos que ejecutan los últimos vuelos de Windows Insider (RS5), compilación 17704 y versiones más recientes.

El Windows Mixed Reality hogar es el punto de partida en el que los usuarios llegan antes de iniciar aplicaciones. De forma predeterminada, debes iniciar aplicaciones y juegos de Win32 VR envolventes desde fuera de los auriculares y no aparecerá en la lista "Todas las aplicaciones" del menú Inicio de Windows Mixed Reality. Si sigues las instrucciones de este artículo para implementar un iniciador de aplicaciones 3D, la experiencia envolvente de Win32 VR se puede iniciar desde el menú inicio de Windows Mixed Reality y el entorno principal.

Esto solo es cierto para experiencias envolventes de Vr de Win32 distribuidas fuera de Steam. En el caso de las experiencias de VR distribuidas a través de Steam, hemos actualizado el Windows Mixed Reality para SteamVR Beta junto con los últimos vuelos de Windows Insider RS5 para que los títulos de SteamVR aparezcan en el menú inicio de Windows Mixed Reality en la lista "Todas las aplicaciones" automáticamente con un iniciador predeterminado. En otras palabras, el método descrito en este artículo no es necesario para los títulos de SteamVR y será reemplazado por la Windows Mixed Reality para la funcionalidad beta de SteamVR.

Proceso de creación del iniciador de aplicaciones 3D

Hay tres pasos para crear un iniciador de aplicaciones 3D:

  1. Diseño y concepto
  2. Modelado y exportación
  3. Integración en la aplicación (este artículo)

Los recursos 3D que se usarán como iniciadores de la aplicación deben crearse mediante las directrices de creación de Windows Mixed Reality para garantizar la compatibilidad. Los recursos que no cumplan esta especificación de creación no se representarán en el Windows Mixed Reality inicio.

Configuración del iniciador 3D

Las aplicaciones Win32 aparecerán en la lista "Todas las aplicaciones" del menú Inicio de Windows Mixed Reality si creas un iniciador de aplicaciones 3D para ellas. Para ello, cree un archivo XML del manifiesto de elementos visuales que haga referencia al iniciador de aplicaciones 3D siguiendo estos pasos:

  1. Cree un archivo GLB del recurso del iniciador de aplicaciones 3D (consulte Modelado y exportación).
  2. Cree un manifiesto de elementos visuales para la aplicación.
    1. Puede empezar con el ejemplo siguiente. Consulte la documentación completa del manifiesto de elementos visuales para obtener más detalles.
    2. Actualiza Square150x150Logo y Square70x70Logo con un PNG/JPG/GIF para tu aplicación.
      • Se usarán para el logotipo 2D de la aplicación en la lista Windows Mixed Reality Todas las aplicaciones y para el menú Inicio en el escritorio.
      • La ruta de acceso del archivo se basa en la carpeta que contiene el manifiesto de elementos visuales.
      • Todavía tienes que proporcionar un icono de menú Inicio de escritorio para tu aplicación a través de los mecanismos estándar. Esto puede estar directamente en el ejecutable o en el acceso directo que cree. Por ejemplo, a través de 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.
    3. Actualice la ruta de acceso mixedRealityModel para que apunte al GLB del iniciador de aplicaciones 3D.
    4. Guarde el archivo con el mismo nombre que el archivo ejecutable, con una extensión de ".VisualElementsManifest.xml" y guárdelo en el mismo directorio. Por ejemplo, para el archivo ejecutable "contoso.exe", el archivo XML adjunto se denomina "contoso.visualelementsmanifest.xml".
  3. Agregue un acceso directo a la aplicación al menú Inicio de Windows de escritorio. Consulte el ejemplo siguiente para obtener un ejemplo de implementación de C++.
    • Créelo en %ALLUSERSPROFILE%\Microsoft\Windows\Menú Inicio\Programas (equipo) o %APPDATA%\Microsoft\Windows\Menú Inicio\Programas (usuario)
    • Si una actualización cambia el manifiesto de elementos visuales o los recursos a los que hace referencia, el actualizador o el instalador deben actualizar el acceso directo de modo que se vuelvan a analizar el manifiesto y se actualicen los recursos almacenados en caché.
  4. Opcional: Si el acceso directo del escritorio no apunta directamente al EXE de la aplicación (por ejemplo, si invoca un controlador de protocolo personalizado como "myapp://"), el menú Inicio no encontrará automáticamente el archivo VisualElementsManifest.xml de la aplicación. Para resolverlo, el acceso directo debe especificar la ruta de acceso del archivo del manifiesto de elementos visuales mediante System.AppUserModel.VisualElementsManifestHintPath (). Esto se puede establecer en el acceso directo con las mismas técnicas que System.AppUserModel.ID. No es necesario usar System.AppUserModel.ID, pero puede hacerlo si desea que el acceso directo coincida con el identificador explícito del modelo de usuario de aplicación de la aplicación si se usa uno. Consulte la sección de creación de accesos directos del iniciador de aplicaciones de ejemplo a continuación para obtener un ejemplo de C++.

Manifiesto de elementos visuales de ejemplo

<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 acceso directo del iniciador de aplicaciones de ejemplo

El código de ejemplo siguiente muestra cómo puede crear un acceso directo en C++, incluida la invalidación de la ruta de acceso al archivo XML del manifiesto de elementos visuales. Tenga en cuenta que la invalidación solo es necesaria en los casos en los que el acceso directo no apunte directamente al EXE asociado al manifiesto (por ejemplo, el acceso directo usa un controlador de protocolo personalizado como "myapp://").

Muestra. Creación de accesos directos de 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;
}

Muestra. Acceso directo del iniciador de direcciones 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

Consulte también