Implementar lançadores de aplicativos 3D (aplicativos Win32)

Nota

Esta funcionalidade apenas está disponível para PCs que executam os mais recentes voos Windows Insider (RS5), construção 17704 e mais recentes.

A casa Windows Mixed Reality é o ponto de partida onde os utilizadores aterram antes de lançarem aplicações. Por padrão, precisa de lançar aplicações e jogos Imersivos Win32 VR de fora dos auscultadores e não aparecerá na lista de "Todas as aplicações" na Windows Mixed Reality menu Iniciar. Se seguir as instruções deste artigo para implementar um lançador de aplicações 3D, a sua experiência imersiva win32 VR pode ser lançada dentro do ambiente Windows Mixed Reality menu Iniciar e doméstico.

Isto só é válido para experiências imersivas do Win32 VR distribuídas fora do Steam. Para experiências vr distribuídas atravésdo Steam, atualizámos o Windows Mixed Reality para SteamVR Beta juntamente com os mais recentes voos insider RS5 Windows para que os títulos do SteamVR apareçam na Windows Mixed Reality menu Iniciar na lista "Todas as aplicações" utilizando automaticamente um lançador padrão. Por outras palavras, o método descrito neste artigo é desnecessário para os títulos steamVR e será ultrapassado pela Windows Mixed Reality para a funcionalidade SteamVR Beta.

Processo de criação de lançador de aplicativos 3D

Existem três passos para criar um lançador de aplicações 3D:

  1. Desenho e conceito
  2. Modelação e exportação
  3. Integrando-o na sua aplicação (este artigo)

Os ativos 3D a utilizar como lançadores para a sua aplicação devem ser da autoria usando as diretrizes de autoria Windows Mixed Reality para garantir a compatibilidade. Os ativos que não cumprirem esta especificação de autoria não serão prestados na casa Windows Mixed Reality.

Configurar o lançador 3D

As aplicações Win32 aparecerão na lista "Todas as aplicações" na Windows Mixed Reality menu Iniciar se criar um lançador de aplicações 3D para as mesmos. Para isso, crie um ficheiro XML manifesto de elementos visuais que faça referência ao Launcher de aplicações 3D seguindo estes passos:

  1. Crie um ficheiro GLB de ativo 3D Launcher (Ver Modelação e exportação).
  2. Crie um Manifesto de Elementos Visuais para a sua aplicação.
    1. Pode começar com a amostra abaixo. Consulte a documentação completa do Manifesto de Elementos Visuais para obter mais detalhes.
    2. Atualize Square150x150Logo e Square70x70Logo com um PNG/JPG/GIF para a sua aplicação.
      • Estes serão utilizados para o logótipo 2D da aplicação na lista Windows Mixed Reality Todas as Aplicações e para o Menu Iniciar no ambiente de trabalho.
      • O percurso do ficheiro baseia-se na pasta que contém o Manifesto de Elementos Visuais.
      • Ainda precisa de fornecer um ícone do Menu Iniciar para o ambiente de trabalho para a sua aplicação através dos mecanismos padrão. Isto pode ser diretamente no executável ou no atalho que cria. Por exemplo, via IShellLink::SetIconLocation.
      • Opcional: Pode utilizar um ficheiro resources.pri se quiser que o MRT forneça vários tamanhos de ativos para diferentes escalas de resolução e temas de alto contraste.
    3. Atualize o Caminho doModel De Realidade Mista para apontar para o GLB para o seu Launcher de Aplicações 3D
    4. Guarde o ficheiro com o mesmo nome do seu ficheiro executável, com uma extensão de ".VisualElementsManifest.xml" e guarde-o no mesmo diretório. Por exemplo, para o ficheiro executável "contoso.exe", o ficheiro XML que o acompanha é denominado "contoso.visualelementsmanifest.xml".
  3. Adicione um atalho à sua aplicação no ambiente de trabalho Windows Menu Iniciar. Consulte a amostra abaixo para obter um exemplo de implementação C++.
    • Crie-o em %ALLUSERSPROFILE%\Microsoft\Microsoft\Windows\Iniciar menu\Programas (máquina) ou %APPDATA%\Microsoft\Microsoft\Windows\Iniciar menu\Programas (utilizador)
    • Se uma atualização alterar os seus elementos visuais manifestar-se ou os ativos por ele referenciados, o atualizador ou instalador deverá atualizar o atalho de modo a que o manifesto seja reparsado e os ativos em cache sejam atualizados.
  4. Opcional: Se o atalho do seu ambiente de trabalho não apontar diretamente para o EXE da sua aplicação (por exemplo, se invocar um manipulador de protocolo personalizado como "myapp://"), o Menu Iniciar não encontrará automaticamente o ficheiro VisualElementsManifest.xml da aplicação. Para resolver isto, o atalho deve especificar o caminho do ficheiro do Manifesto de Elementos Visuais utilizando o System.AppUserModel.VisualElementsManifestHintPath (). Isto pode ser definido no atalho utilizando as mesmas técnicas que System.AppUserModel.ID. Não é obrigado a utilizar System.AppUserModel.ID mas pode fazê-lo se desejar que o atalho corresponda ao ID explícito do Modelo de Utilizador da aplicação se for utilizado. Consulte a secção de criação de atalho do lançador de aplicações de amostra abaixo para obter uma amostra C++.

Manifesto de Elementos Visuais da Amostra

<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 de lançador de aplicativos de amostra

O código de amostra abaixo mostra como pode criar um atalho em C++, incluindo a sobrepor o caminho para o ficheiro Manifesto de Elementos Visuais XML. Note que a sobreposição só é necessária nos casos em que o seu atalho não aponta diretamente para o EXE associado ao manifesto (por exemplo, o seu atalho utiliza um manipulador de protocolo personalizado como "myapp://").

Amostra. Criação de atalho 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;
}

Amostra. Atalho do lançador 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

Ver também