Implementar inicializadores de aplicativo 3D (aplicativos Win32)Implement 3D app launchers (Win32 apps)

Observação

Esse recurso só está disponível para computadores que executam os vôos mais recentes do Windows Insider (RS5), compilação 17704 e mais recente.This feature is only available to PCs running the latest Windows Insider flights (RS5), build 17704 and newer.

O Windows Mixed Reality Home é o ponto de partida onde os usuários vão antes de iniciar os aplicativos.The Windows Mixed Reality home is the starting point where users land before launching applications. Por padrão, os aplicativos e jogos de imersão do Win32 devem ser iniciados de fora do headset e não aparecerão na lista "todos os aplicativos" no menu Iniciar da realidade do Windows Mixed.By default, immersive Win32 VR apps and games have to be launched from outside the headset and won't appear in the "All apps" list on the Windows Mixed Reality Start menu. No entanto, seguindo as instruções neste artigo para implementar um inicializador de aplicativo 3D, sua experiência de imersão do Win32 VR pode ser iniciada no menu iniciar e no ambiente inicial do Windows Mixed Reality.However, by following 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.

Isso só é verdadeiro para experiências de imersão do Win32 distributied fora do fluxo.This is only true for immersive Win32 VR experiences distributied outside of Steam. Para experiências de VR distribuídas por meio do vapor, atualizamos a realidade mista do Windows para SteamVR beta junto com os vôos do Windows Insider RS5 mais recentes para que os títulos de SteamVR sejam exibidos no menu Iniciar do Windows Mixed Reality na lista "todos os aplicativos" automaticamente usando um iniciador padrão.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. Em outras palavras, o método descrito neste artigo é desnecessário para títulos SteamVR e será substituído pela funcionalidade 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.

processo de criação do inicializador de aplicativo 3D3D app launcher creation process

Há três etapas para criar um iniciador de aplicativo 3D:There are 3 steps to creating a 3D app launcher:

  1. Design e conceitoDesigning and concepting
  2. Modelagem e exportaçãoModeling and exporting
  3. Integrando-o ao seu aplicativo (este artigo)Integrating it into your application (this article)

os ativos 3D a serem usados como iniciadores para seu aplicativo devem ser criados usando as diretrizes de criação do Windows Mixed Reality para garantir a compatibilidade.3D assets to be used as launchers for your application should be authored using the Windows Mixed Reality authoring guidelines to ensure compatibility. Os ativos que não atenderem a essa especificação de criação não serão renderizados na página inicial do Windows Mixed Reality.Assets that fail to meet this authoring specification will not be rendered in the Windows Mixed Reality home.

Configurando o iniciador 3DConfiguring the 3D launcher

Os aplicativos Win32 serão exibidos na lista "todos os aplicativos" no menu Iniciar do Windows Mixed Reality se você criar um inicializador de aplicativo 3D para eles.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 fazer isso, crie um arquivo XML de manifesto de elementos visuais referenciando o iniciador do aplicativo 3D seguindo estas etapas:To do that, create a Visual Elements Manifest XML file referencing the 3D App Launcher by following these steps:

  1. Crie um arquivo glb do ativo do iniciador de aplicativo 3D (consulte modelagem e exportação).Create a 3D App Launcher asset GLB file (See Modeling and exporting).
  2. Crie um manifesto de elementos visuais para seu aplicativo.Create a Visual Elements Manifest for your application.
    1. Você pode começar com o exemplo abaixo.You can start with the sample below. Consulte a documentação de manifesto de elementos visuais completos para obter mais detalhes.See the full Visual Elements Manifest documentation for more details.
    2. Atualize Square150x150Logo e SQUARE70X70LOGO com um png/jpg/gif para seu aplicativo.Update Square150x150Logo and Square70x70Logo with a PNG/JPG/GIF for your app.
      • Eles serão usados para o logotipo 2D do aplicativo na lista todos os aplicativos do Windows Mixed Reality e para o menu iniciar na área de trabalho.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.
      • O caminho do arquivo é relativo à pasta que contém o manifesto dos elementos visuais.The file path is relative to the folder containing the Visual Elements Manifest.
      • Você ainda precisa fornecer um ícone do menu Iniciar do desktop para seu aplicativo por meio dos mecanismos padrão.You still need to provide a desktop Start Menu icon for your app through the standard mechanisms. Isso pode ser diretamente no executável ou no atalho que você criar (por exemplo, via IShellLink:: SetIconLocation).This can either be directly in the executable or in the shortcut you create (e.g. via IShellLink::SetIconLocation).
      • Opcional: Você pode usar um arquivo Resources. pri se desejar que o MRT forneça vários tamanhos de ativos para diferentes escalas de resolução e temas de alto contraste.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. Atualize o caminho do MixedRealityModel para apontar para o glb para o iniciador do aplicativo 3DUpdate the MixedRealityModel Path to point to the GLB for your 3D App Launcher
    4. Salve o arquivo com o mesmo nome do arquivo executável, com uma extensão de ". VisualElementsManifest. xml "e salve-o no mesmo diretório.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 exemplo, para o arquivo executável "contoso. exe", o arquivo XML que o acompanha é denominado "contoso. visualelementsmanifest. xml".For example, for the executable file "contoso.exe", the accompanying XML file is named "contoso.visualelementsmanifest.xml".
  3. Adicione um atalho ao seu aplicativo no menu Iniciar do Windows da área de trabalho.Add a shortcut to your application to the desktop Windows Start Menu. Consulte o exemplo abaixo para obter uma C++ implementação de exemplo.See the sample below for an example C++ implementation.
    • Criá-lo em%ALLUSERSPROFILE%\Microsoft\Windows\Start Iniciar\programas (Machine) ou%APPDATA%\Microsoft\Windows\Start Iniciar\programas (User)Create it in %ALLUSERSPROFILE%\Microsoft\Windows\Start Menu\Programs (machine) or %APPDATA%\Microsoft\Windows\Start Menu\Programs (user)
    • Se uma atualização alterar o manifesto dos elementos visuais ou os ativos referenciados por ele, o atualizador ou o instalador deverá atualizar o atalho de modo que o manifesto seja analisado e os ativos em cache sejam atualizados.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: Se o seu atalho de área de trabalho não apontar diretamente para o EXE do seu aplicativo (por exemplo, se ele invocar um manipulador de protocolo personalizado como "myapp://"), o menu Iniciar não localizará automaticamente o arquivo VisualElementsManifest. XML do aplicativo.Optional: If your desktop shortcut does not point directly to your application’s EXE (e.g., if it invokes a custom protocol handler like “myapp://”), the Start Menu won’t automatically find the app’s VisualElementsManifest.xml file. Para resolver isso, o atalho deve especificar o caminho do arquivo do manifesto dos elementos visuais usando System. AppUserModel. VisualElementsManifestHintPath ().To resolve this, the shortcut should specify the file path of the Visual Elements Manifest using System.AppUserModel.VisualElementsManifestHintPath (). Isso pode ser definido no atalho usando as mesmas técnicas que System.AppUserModel.ID.This can be set in the shortcut using the same techniques as System.AppUserModel.ID. Não é necessário usar System.AppUserModel.ID, mas você pode fazer isso se desejar que o atalho corresponda à ID do modelo de usuário do aplicativo explícito, se um for usado.You are not 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. Consulte a seção criação de atalho do iniciador de aplicativo de exemplo abaixo para obter um C++ exemplo.See the sample app launcher shortcut creation section below for a C++ sample.

Manifesto de elementos visuais de exemploSample 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>

Criação de atalho do iniciador de aplicativo de exemploSample app launcher shortcut creation

O código de exemplo abaixo mostra como você pode criar um atalho C++no, incluindo a substituição do caminho para o arquivo XML de manifesto dos elementos visuais.The sample code below shows how you can create a shortcut in C++, including overriding the path to the Visual Elements Manifest XML file. Observe que a substituição só é necessária nos casos em que o atalho não aponta diretamente para o EXE associado ao manifesto (por exemplo,Note the override is only required in cases where your shortcut does not point directly to the EXE associated with the manifest (eg. o atalho usa um manipulador de protocolo personalizado como "myapp://").your shortcut uses a custom protocol handler like "myapp://").

Nova. Criação de atalho LNKC++()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;
}

Nova. Atalho do inicializador 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 tambémSee also