Como obter um HolographicSpaceGetting a HolographicSpace

Observação

Este artigo está relacionado às APIs nativas do WinRT herdadas.This article relates to the legacy WinRT native APIs. Para novos projetos de aplicativos nativos, é recomendável usar a API OpenXR.For new native app projects, we recommend using the OpenXR API.

A classe HolographicSpace é o seu portal no mundo Holographic.The HolographicSpace class is your portal into the holographic world. Ele controla a renderização de imersão, fornece dados de câmera e fornece acesso a APIs de raciocínio espacial.It controls immersive rendering, provides camera data, and provides access to spatial reasoning APIs. Você criará um para o CoreWindow do seu aplicativo UWP ou o HWND do seu aplicativo Win32.You'll create one for your UWP app's CoreWindow or your Win32 app's HWND.

Configurar o espaço HolographicSet up the holographic space

Criar o objeto Holographic Space é a primeira etapa para tornar seu aplicativo Windows Mixed Reality.Creating the holographic space object is the first step in making your Windows Mixed Reality app. Os aplicativos tradicionais do Windows são renderizados para uma cadeia de permuta do Direct3D criada para a janela principal de sua exibição de aplicativo.Traditional Windows apps render to a Direct3D swap chain created for the core window of their application view. Essa cadeia de permuta é exibida para um Slate na interface do usuário do amholographic.This swap chain is displayed to a slate in the holographic UI. Para fazer com que seu aplicativo exiba Holographic em vez de um Tablet 2D, crie um espaço Holographic para sua janela principal em vez de uma cadeia de permuta.To make your application view holographic rather than a 2D slate, create a holographic space for its core window instead of a swap chain. Apresentar quadros Holographic criados por esse espaço de Holographic coloca seu aplicativo no modo de renderização de tela inteira.Presenting holographic frames that are created by this holographic space puts your app into full-screen rendering mode.

Para um aplicativo UWP a partir do modelo de aplicativo Holographic DirectX 11 (universal do Windows), procure esse código no método SetWindow em AppView. cpp:For a UWP app starting from the Holographic DirectX 11 App (Universal Windows) template, look for this code in the SetWindow method in AppView.cpp:

m_holographicSpace = HolographicSpace::CreateForCoreWindow(window);

Se você estiver criando um aplicativo Win32 a partir do exemplo do Win32 BasicHologram, examine o aplicativo:: CreateWindowAndHolographicSpace para obter um exemplo de HWND.If you're building a Win32 app starting from the BasicHologram Win32 sample, look at App::CreateWindowAndHolographicSpace for an HWND example. Em seguida, você pode convertê-lo em um HWND de imersão criando um HolographicSpaceassociado:You can then convert it into an immersive HWND by creating an associated HolographicSpace:

void App::CreateWindowAndHolographicSpace(HINSTANCE hInstance, int nCmdShow)
{
    // Store the instance handle in our class variable.
    m_hInst = hInstance;

    // Create the window for the HolographicSpace.
    hWnd = CreateWindowW(
        m_szWindowClass, 
        m_szTitle,
        WS_VISIBLE,
        CW_USEDEFAULT, 
        0, 
        CW_USEDEFAULT, 
        0, 
        nullptr, 
        nullptr, 
        hInstance, 
        nullptr);

    if (!hWnd)
    {
        winrt::check_hresult(E_FAIL);
    }

    {
        // Use WinRT factory to create the holographic space.
        using namespace winrt::Windows::Graphics::Holographic;
        winrt::com_ptr<IHolographicSpaceInterop> holographicSpaceInterop =
            winrt::get_activation_factory<HolographicSpace, IHolographicSpaceInterop>();
        winrt::com_ptr<ABI::Windows::Graphics::Holographic::IHolographicSpace> spHolographicSpace;
        winrt::check_hresult(holographicSpaceInterop->CreateForWindow(
            hWnd, __uuidof(ABI::Windows::Graphics::Holographic::IHolographicSpace),
            winrt::put_abi(spHolographicSpace)));

        if (!spHolographicSpace)
        {
            winrt::check_hresult(E_FAIL);
        }

        // Store the holographic space.
        m_holographicSpace = spHolographicSpace.as<HolographicSpace>();
    }

    // The DeviceResources class uses the preferred DXGI adapter ID from the holographic
    // space (when available) to create a Direct3D device. The HolographicSpace
    // uses this ID3D11Device to create and manage device-based resources such as
    // swap chains.
    m_deviceResources->SetHolographicSpace(m_holographicSpace);

    // The main class uses the holographic space for updates and rendering.
    m_main->SetHolographicSpace(hWnd, m_holographicSpace);

    // Show the window. This will activate the holographic view and switch focus
    // to the app in Windows Mixed Reality.
    ShowWindow(hWnd, nCmdShow);
    UpdateWindow(hWnd);
}

Depois de obter um HolographicSpace para o seu CoreWindow UWP ou o HWND do Win32, o HolographicSpace pode lidar com as câmeras de Holographic, criar sistemas de coordenadas e fazer Holographic renderização.Once you've obtained a HolographicSpace for either your UWP CoreWindow or Win32 HWND, the HolographicSpace can handle holographic cameras, create coordinate systems, and do holographic rendering. O espaço Holographic atual é usado em vários locais no modelo do DirectX:The current holographic space is used in multiple places in the DirectX template:

  • A classe DeviceResources precisa obter algumas informações do objeto HolographicSpace para criar o dispositivo Direct3D.The DeviceResources class needs to get some information from the HolographicSpace object to create the Direct3D device. Esta é a ID do adaptador DXGI associada à exibição Holographic.This is the DXGI adapter ID associated with the holographic display. A classe HolographicSpace usa o dispositivo Direct3D 11 de seu aplicativo para criar e gerenciar recursos baseados em dispositivo, como os buffers de fundo para cada câmera Holographic.The HolographicSpace class uses your app's Direct3D 11 device to create and manage device-based resources, such as the back buffers for each holographic camera. Se você estiver interessado em ver o que essa função faz nos bastidores, você a encontrará em DeviceResources. cpp.If you're interested in seeing what this function does under the hood, you'll find it in DeviceResources.cpp.
  • A função DeviceResources:: InitializeUsingHolographicSpace demonstra como obter o adaptador pesquisando a LUID – e como escolher um adaptador padrão quando nenhum adaptador preferencial for especificado.The function DeviceResources::InitializeUsingHolographicSpace demonstrates how to obtain the adapter by looking up the LUID – and how to choose a default adapter when no preferred adapter is specified.
  • A classe principal do aplicativo usa o espaço Holographic de AppView:: SetWindow ou App:: CreateWindowAndHolographicSpace para atualizações e renderização.The app's main class uses the holographic space from AppView::SetWindow or App::CreateWindowAndHolographicSpace for updates and rendering.

Observação

Embora as seções a seguir mencionem nomes de funções do modelo, como AppView:: SetWindow , que pressupõem que você começou do modelo de aplicativo Holographic UWP, os trechos de código que você vê serão aplicados igualmente entre os aplicativos UWP e Win32.While the sections below mention function names from the template like AppView::SetWindow that assume that you started from the holographic UWP app template, the code snippets you see will apply equally across UWP and Win32 apps.

Em seguida, vamos nos aprofundar no processo de configuração que SetHolographicSpace é responsável pela classe AppMain.Next, we'll dive into the setup process that SetHolographicSpace is responsible for in the AppMain class.

Assinar eventos de câmera, criar e remover recursos de câmeraSubscribe to camera events, create, and remove camera resources

O conteúdo do Holographic do aplicativo reside em seu espaço de Holographic e é exibido por meio de uma ou mais câmeras de Holographic, que representam perspectivas diferentes na cena.Your app's holographic content lives in its holographic space, and is viewed through one or more holographic cameras, which represent different perspectives on the scene. Agora que você tem o espaço Holographic, você pode receber dados para câmeras Holographic.Now that you have the holographic space, you can receive data for holographic cameras.

Seu aplicativo precisa responder a eventos do CameraAdded criando qualquer recurso que seja específico para essa câmera.Your app needs to respond to CameraAdded events by creating any resources that are specific to that camera. Um exemplo desse recurso é a exibição de destino de renderização de buffer de fundo.An example of such a resource is your back buffer render target view. Você pode ver esse código na função DeviceResources:: SetHolographicSpace , chamada por AppView:: SetWindow antes que o aplicativo crie qualquer quadro de Holographic:You can see this code in the DeviceResources::SetHolographicSpace function, called by AppView::SetWindow before the app creates any holographic frames:

m_cameraAddedToken = m_holographicSpace.CameraAdded(
    std::bind(&AppMain::OnCameraAdded, this, _1, _2));

Seu aplicativo também precisa responder a eventos do CameraRemoved liberando recursos que foram criados para essa câmera.Your app also needs to respond to CameraRemoved events by releasing resources that were created for that camera.

De DeviceResources:: SetHolographicSpace:From DeviceResources::SetHolographicSpace:

m_cameraRemovedToken = m_holographicSpace.CameraRemoved(
    std::bind(&AppMain::OnCameraRemoved, this, _1, _2));

Os manipuladores de eventos devem concluir algum trabalho para manter a renderização de Holographic fluindo sem problemas, e a renderização do aplicativo.The event handlers must complete some work to keep holographic rendering flowing smoothly, and your app rendering at all. Leia o código e os comentários para obter os detalhes: você pode procurar OnCameraAdded e OnCameraRemoved em sua classe principal para entender como o mapa de m_cameraResources é tratado pelo DeviceResources.Read the code and comments for the details: you can look for OnCameraAdded and OnCameraRemoved in your main class to understand how the m_cameraResources map is handled by DeviceResources.

No momento, estamos concentrados no AppMain e na configuração que ele faz para permitir que seu aplicativo saiba sobre câmeras Holographic.Right now, we're focused on AppMain and the setup that it does to enable your app to know about holographic cameras. Com isso em mente, é importante anotar os dois requisitos a seguir:With this in mind, it's important to take note of the following two requirements:

  1. Para o manipulador de eventos CameraAdded , o aplicativo pode trabalhar de forma assíncrona para concluir a criação de recursos e o carregamento de ativos para a nova câmera Holographic.For the CameraAdded event handler, the app can work asynchronously to finish creating resources and loading assets for the new holographic camera. Os aplicativos que levam mais de um quadro para concluir esse trabalho devem solicitar um adiamento e concluir o adiamento após o carregamento de forma assíncrona.Apps that take more than one frame to complete this work should request a deferral, and complete the deferral after loading asynchronously. Uma tarefa ppl pode ser usada para fazer trabalhos assíncronos.A PPL task can be used to do asynchronous work. Seu aplicativo deve garantir que esteja pronto para renderizar para essa câmera imediatamente quando ele sair do manipulador de eventos ou quando concluir o adiamento.Your app must ensure that it's ready to render to that camera right away when it exits the event handler, or when it completes the deferral. A saída do manipulador de eventos ou a conclusão do adiamento diz ao sistema que seu aplicativo agora está pronto para receber quadros Holographic com essa câmera incluída.Exiting the event handler or completing the deferral tells the system that your app is now ready to receive holographic frames with that camera included.

  2. Quando o aplicativo recebe um evento CameraRemoved , ele deve liberar todas as referências para o buffer de fundo e sair da função imediatamente.When the app receives a CameraRemoved event, it must release all references to the back buffer and exit the function right away. Isso inclui exibições de destino de renderização e qualquer outro recurso que possa conter uma referência para o IDXGIResource.This includes render target views, and any other resource that might hold a reference to the IDXGIResource. O aplicativo também deve garantir que o buffer de fundo não seja anexado como um destino de renderização, conforme mostrado em CameraResources:: ReleaseResourcesForBackBuffer.The app must also ensure that the back buffer isn't attached as a render target, as shown in CameraResources::ReleaseResourcesForBackBuffer. Para ajudar a acelerar as coisas, seu aplicativo pode liberar o buffer de fundo e, em seguida, iniciar uma tarefa para concluir de forma assíncrona qualquer outro trabalho de subdivisão para a câmera.To help speed things along, your app can release the back buffer and then launch a task to asynchronously complete any other tear down work for the camera. O modelo de aplicativo Holographic inclui uma tarefa PPL que você pode usar para essa finalidade.The holographic app template includes a PPL task that you can use for this purpose.

Observação

Se você quiser determinar quando uma câmera adicionada ou removida aparece no quadro, use as propriedades HolographicFrame AddedCameras e RemovedCameras .If you want to determine when an added or removed camera shows up on the frame, use the HolographicFrame AddedCameras and RemovedCameras properties.

Criar um quadro de referência para o conteúdo do HolographicCreate a frame of reference for your holographic content

O conteúdo do aplicativo deve ser posicionado em um sistema de coordenadas espaciais a ser processado no HolographicSpace.Your app's content must be positioned in a spatial coordinate system to be rendered in the HolographicSpace. O sistema fornece dois quadros principais de referência, que podem ser usados para estabelecer um sistema de coordenadas para seus hologramas.The system provides two primary frames of reference, which you can use to establish a coordinate system for your holograms.

Há dois tipos de quadros de referência no Windows Holographic: quadros de referência anexados ao dispositivo e quadros de referência que permanecem estacionários à medida que o dispositivo passa pelo ambiente do usuário.There are two kinds of reference frames in Windows Holographic: reference frames attached to the device, and reference frames that remain stationary as the device moves through the user's environment. O modelo de aplicativo Holographic usa um quadro de referência estacionário por padrão; Essa é uma das maneiras mais simples de renderizar hologramas com bloqueios mundiais.The holographic app template uses a stationary reference frame by default; this is one of the simplest ways to render world-locked holograms.

Quadros de referência estacionários são projetados para estabilizar posições perto do local atual do dispositivo.Stationary reference frames are designed to stabilize positions near the device's current location. Isso significa que as coordenadas mais adiante do dispositivo podem descompassor um pouco em relação ao ambiente do usuário, pois o dispositivo aprende mais sobre o espaço em torno dele.This means that coordinates further from the device can drift slightly relative to the user's environment as the device learns more about the space around it. Há duas maneiras de criar um quadro estacionário de referência: Adquira o sistema de coordenadas do estágio espacialou use o SpatialLocatorpadrão.There are two ways to create a stationary frame of reference: acquire the coordinate system from the spatial stage, or use the default SpatialLocator. Se você estiver criando um aplicativo de realidade mista do Windows para headsets de imersão, o ponto de partida recomendado será o estágio espacial.If you're creating a Windows Mixed Reality app for immersive headsets, the recommended starting point is the spatial stage. O estágio espacial também fornece informações sobre os recursos do headset de imersão gastados pelo jogador.The spatial stage also provides information about the capabilities of the immersive headset worn by the player. Aqui, mostramos como usar o SpatialLocatorpadrão.Here, we show how to use the default SpatialLocator.

O localizador espacial representa o dispositivo Windows Mixed Reality e rastreia o movimento do dispositivo e fornece sistemas de coordenadas que podem ser compreendidos em relação à sua localização.The spatial locator represents the Windows Mixed Reality device, and tracks the motion of the device and provides coordinate systems that can be understood relative to its location.

De AppMain:: OnHolographicDisplayIsAvailableChanged:From AppMain::OnHolographicDisplayIsAvailableChanged:

spatialLocator = SpatialLocator::GetDefault();

Crie o quadro de referência estacionário uma vez quando o aplicativo for iniciado.Create the stationary reference frame once when the app is launched. Isso é análogo à definição de um sistema de coordenadas mundiais, com a origem colocada na posição do dispositivo quando o aplicativo é iniciado.This is analogous to defining a world coordinate system, with the origin placed at the device's position when the app is launched. Este quadro de referência não se move com o dispositivo.This reference frame doesn't move with the device.

De AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

m_stationaryReferenceFrame =
    m_spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

Todos os quadros de referência estão alinhados com a gravidade, o que significa que o eixo y aponta "para cima" em relação ao ambiente do usuário.All reference frames are gravity aligned, meaning that the y-axis points "up" in relation to the user's environment. Como o Windows usa sistemas de coordenadas "destros", a direção do eixo – z coincide com a direção "encaminhar" que o dispositivo está enfrentando quando o quadro de referência é criado.Since Windows uses "right-handed" coordinate systems, the direction of the –z axis coincides with the "forward" direction the device is facing when the reference frame is created.

Observação

Quando seu aplicativo exige o posicionamento preciso de hologramas individuais, use um SpatialAnchor para ancorar o holograma individual em uma posição no mundo real.When your app requires precise placement of individual holograms, use a SpatialAnchor to anchor the individual hologram to a position in the real world. Por exemplo, use uma âncora espacial quando o usuário indicar um ponto para ser um interesse especial.For example, use a spatial anchor when the user indicates a point to be of special interest. As posições de âncora não são descompassos, mas podem ser ajustadas.Anchor positions do not drift, but they can be adjusted. Por padrão, quando uma âncora é ajustada, ela facilita sua posição nos próximos vários quadros depois que a correção ocorre.By default, when an anchor is adjusted, it eases its position into place over the next several frames after the correction has occurred. Dependendo do seu aplicativo, quando isso ocorrer, talvez você queira lidar com o ajuste de uma maneira diferente (por exemplo, adiando-o até que o holograma esteja fora da exibição).Depending on your application, when this occurs you may want to handle the adjustment in a different manner (e.g. by deferring it until the hologram is out of view). A propriedade RawCoordinateSystem e os eventos RawCoordinateSystemAdjusted permitem essas personalizações.The RawCoordinateSystem property and RawCoordinateSystemAdjusted events enable these customizations.

Responder a eventos alterados do locatabilityRespond to locatability changed events

A renderização de hologramas bloqueados no mundo requer que o dispositivo se localize no mundo inteiro.Rendering world-locked holograms requires the device to locate itself in the world. Isso nem sempre pode ser possível por causa de condições ambientais e, nesse caso, o usuário pode esperar uma indicação visual da interrupção do controle.This may not always be possible because of environmental conditions, and if so, the user may expect a visual indication of the tracking interruption. Essa indicação visual deve ser renderizada usando quadros de referência anexados ao dispositivo, em vez de ser estacionário ao mundo.This visual indication must be rendered using reference frames attached to the device, instead of stationary to the world.

Seu aplicativo pode solicitar a notificação se o rastreamento for interrompido por qualquer motivo.Your app can request to be notified if tracking is interrupted for any reason. Registre-se no evento LocatabilityChanged para detectar quando a capacidade do dispositivo de se localizar no mundo é alterada.Register for the LocatabilityChanged event to detect when the device's ability to locate itself in the world changes. De AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

m_locatabilityChangedToken = m_spatialLocator.LocatabilityChanged(
    std::bind(&HolographicApp6Main::OnLocatabilityChanged, this, _1, _2));

Em seguida, use esse evento para determinar quando os hologramas não podem ser renderizados como estáticos para o mundo.Then use this event to determine when holograms cannot be rendered stationary to the world.

Confira tambémSee also