Ottenere un HolographicSpaceGetting a HolographicSpace

Nota

Questo articolo si riferisce alle API native di WinRT legacy.This article relates to the legacy WinRT native APIs. Per i nuovi progetti di app native, è consigliabile usare l' API OpenXR.For new native app projects, we recommend using the OpenXR API.

La classe HolographicSpace è il portale nel mondo olografico.The HolographicSpace class is your portal into the holographic world. Controlla il rendering immersivo, fornisce i dati della fotocamera e fornisce l'accesso alle API di ragionamento spaziale.It controls immersive rendering, provides camera data, and provides access to spatial reasoning APIs. Ne verrà creato uno per il CoreWindow dell'app UWP o l'HWND dell'app Win32.You'll create one for your UWP app's CoreWindow or your Win32 app's HWND.

Configurare lo spazio olograficoSet up the holographic space

La creazione dell'oggetto spazio olografico è il primo passaggio per creare un'app per la realtà mista di Windows.Creating the holographic space object is the first step in making your Windows Mixed Reality app. Le applicazioni Windows tradizionali eseguono il rendering di una catena di scambio Direct3D creata per la finestra principale della visualizzazione dell'applicazione.Traditional Windows apps render to a Direct3D swap chain created for the core window of their application view. Questa catena di scambio viene visualizzata in uno Slate nell'interfaccia utente olografica.This swap chain is displayed to a slate in the holographic UI. Per rendere olografica la visualizzazione dell'applicazione anziché una lavagna 2D, creare uno spazio olografico per la finestra principale anziché una catena di scambio.To make your application view holographic rather than a 2D slate, create a holographic space for its core window instead of a swap chain. La presentazione di frame olografici creati da questo spazio olografico consente di inserire l'app in modalità di rendering a schermo intero.Presenting holographic frames that are created by this holographic space puts your app into full-screen rendering mode.

Per un' app UWP a partire dal modello di app DirectX 11 (Windows universale) olografico, cercare questo codice nel metodo sewindow in 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 si sta creando un' app Win32 a partire dall'esempio Win32 BasicHologram, vedere app:: CreateWindowAndHolographicSpace per un esempio di HWND.If you're building a Win32 app starting from the BasicHologram Win32 sample, look at App::CreateWindowAndHolographicSpace for an HWND example. È quindi possibile convertirlo in un HWND immersivo creando un HolographicSpaceassociato: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);
}

Una volta ottenuto un HolographicSpace per UWP CoreWindow o l'HWND Win32, il HolographicSpace può gestire le fotocamere olografiche, creare sistemi di coordinate ed eseguire il rendering olografico.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. Lo spazio olografico corrente viene usato in più posizioni nel modello DirectX:The current holographic space is used in multiple places in the DirectX template:

  • La classe DeviceResources deve ottenere alcune informazioni dall'oggetto HolographicSpace per creare il dispositivo Direct3D.The DeviceResources class needs to get some information from the HolographicSpace object to create the Direct3D device. ID adattatore DXGI associato alla visualizzazione olografica.This is the DXGI adapter ID associated with the holographic display. La classe HolographicSpace usa il dispositivo Direct3D 11 dell'app per creare e gestire risorse basate su dispositivo, ad esempio i buffer indietro per ogni fotocamera olografica.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 si è interessati a vedere il funzionamento di questa funzione sotto la cappa, è possibile trovarla in DeviceResources. cpp.If you're interested in seeing what this function does under the hood, you'll find it in DeviceResources.cpp.
  • La funzione DeviceResources:: InitializeUsingHolographicSpace illustra come ottenere l'adapter cercando LUID e come scegliere una scheda predefinita se non è specificata alcuna scheda preferita.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.
  • La classe principale dell'app usa lo spazio olografico di AppView:: sewindow o app:: CreateWindowAndHolographicSpace per gli aggiornamenti e il rendering.The app's main class uses the holographic space from AppView::SetWindow or App::CreateWindowAndHolographicSpace for updates and rendering.

Nota

Mentre le sezioni seguenti menzionano i nomi di funzione del modello come AppView:: sefinestra che presuppone che sia stato avviato dal modello di app UWP olografico, i frammenti di codice visualizzati verranno applicati equamente nelle app 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.

Successivamente, verrà analizzato il processo di installazione di cui SetHolographicSpace è responsabile nella classe AppMain.Next, we'll dive into the setup process that SetHolographicSpace is responsible for in the AppMain class.

Sottoscrivere gli eventi della fotocamera, creare e rimuovere le risorse della fotocameraSubscribe to camera events, create, and remove camera resources

Il contenuto olografico dell'app si trova nello spazio olografico e viene visualizzato tramite una o più fotocamere olografiche, che rappresentano prospettive diverse sulla scena.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. Ora che si dispone dello spazio olografico, è possibile ricevere i dati per le fotocamere olografiche.Now that you have the holographic space, you can receive data for holographic cameras.

L'app deve rispondere agli eventi CameraAdded creando le risorse specifiche per la fotocamera.Your app needs to respond to CameraAdded events by creating any resources that are specific to that camera. Un esempio di tale risorsa è la visualizzazione della destinazione di rendering del buffer nascosto.An example of such a resource is your back buffer render target view. È possibile visualizzare questo codice nella funzione DeviceResources:: SetHolographicSpace , chiamato da AppView:: sefinestra prima che l'app crei qualsiasi frame olografico: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));

L'app deve anche rispondere agli eventi CameraRemoved rilasciando le risorse create per la fotocamera.Your app also needs to respond to CameraRemoved events by releasing resources that were created for that camera.

Da DeviceResources:: SetHolographicSpace:From DeviceResources::SetHolographicSpace:

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

I gestori di eventi devono completare alcune operazioni per garantire che il rendering olografico scorra senza problemi e il rendering dell'app.The event handlers must complete some work to keep holographic rendering flowing smoothly, and your app rendering at all. Leggere il codice e i commenti per i dettagli: è possibile cercare OnCameraAdded e OnCameraRemoved nella classe principale per comprendere in che modo la mappa m_cameraResources viene gestita da 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.

A questo punto, ci siamo concentrati su AppMain e sulla configurazione che consente all'app di sapere sulle fotocamere olografiche.Right now, we're focused on AppMain and the setup that it does to enable your app to know about holographic cameras. Tenendo presente questo aspetto, è importante prendere in considerazione i due requisiti seguenti:With this in mind, it's important to take note of the following two requirements:

  1. Per il gestore dell'evento CameraAdded , l'app può funzionare in modo asincrono per completare la creazione di risorse e il caricamento di asset per la nuova fotocamera olografica.For the CameraAdded event handler, the app can work asynchronously to finish creating resources and loading assets for the new holographic camera. Le app che accettano più di un frame per completare questa operazione devono richiedere un rinvio e completare il rinvio dopo il caricamento asincrono.Apps that take more than one frame to complete this work should request a deferral, and complete the deferral after loading asynchronously. Un' attività PPL può essere utilizzata per eseguire operazioni asincrone.A PPL task can be used to do asynchronous work. L'app deve assicurarsi che sia pronta per il rendering della fotocamera immediatamente quando esce dal gestore eventi o quando completa il rinvio.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. Se si esce dal gestore eventi o si completa il rinvio, viene indicato al sistema che l'app è ora pronta a ricevere i frame olografici con la fotocamera inclusa.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 l'app riceve un evento CameraRemoved , deve rilasciare tutti i riferimenti al buffer nascosto e chiudere immediatamente la funzione.When the app receives a CameraRemoved event, it must release all references to the back buffer and exit the function right away. Sono incluse le visualizzazioni della destinazione di rendering e qualsiasi altra risorsa che può includere un riferimento a IDXGIResource.This includes render target views, and any other resource that might hold a reference to the IDXGIResource. L'app deve inoltre assicurarsi che il buffer nascosto non sia collegato come destinazione di rendering, come illustrato in CameraResources:: ReleaseResourcesForBackBuffer.The app must also ensure that the back buffer isn't attached as a render target, as shown in CameraResources::ReleaseResourcesForBackBuffer. Per velocizzare le operazioni, l'app può rilasciare il buffer nascosto e avviare un'attività per completare in modo asincrono eventuali altre operazioni di chiusura per la fotocamera.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. Il modello di app olografico include un'attività PPL che è possibile usare a questo scopo.The holographic app template includes a PPL task that you can use for this purpose.

Nota

Per determinare quando viene visualizzata una fotocamera aggiunta o rimossa nel frame, usare le proprietà 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.

Creare un frame di riferimento per il contenuto olograficoCreate a frame of reference for your holographic content

Il contenuto dell'app deve essere posizionato in un sistema di coordinate spaziali per poter essere sottoposto a rendering nella HolographicSpace.Your app's content must be positioned in a spatial coordinate system to be rendered in the HolographicSpace. Il sistema fornisce due frame primari di riferimento, che è possibile usare per definire un sistema di coordinate per gli ologrammi.The system provides two primary frames of reference, which you can use to establish a coordinate system for your holograms.

Sono disponibili due tipi di frame di riferimento in Windows olografico: frame di riferimento collegati al dispositivo e frame di riferimento che rimangono fissi quando il dispositivo viene spostato nell'ambiente dell'utente.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. Per impostazione predefinita, il modello di applicazione olografica usa un frame di riferimento fisso. Questo è uno dei modi più semplici per eseguire il rendering degli ologrammi con blocco mondiale.The holographic app template uses a stationary reference frame by default; this is one of the simplest ways to render world-locked holograms.

I frame di riferimento stazionari sono progettati per stabilizzare le posizioni vicino alla posizione corrente del dispositivo.Stationary reference frames are designed to stabilize positions near the device's current location. Ciò significa che le coordinate aggiuntive del dispositivo possono essere leggermente ripartite rispetto all'ambiente dell'utente, perché il dispositivo apprende altre informazioni sullo spazio.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. Esistono due modi per creare un frame di riferimento stazionario: acquisire il sistema di coordinate dalla fase spazialeoppure usare il valore predefinito SpatialLocator.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 si sta creando un'app di realtà mista di Windows per auricolari immersivi, il punto di partenza consigliato è la fase spaziale.If you're creating a Windows Mixed Reality app for immersive headsets, the recommended starting point is the spatial stage. La fase spaziale fornisce inoltre informazioni sulle funzionalità dell'auricolare immersivo utilizzato dal lettore.The spatial stage also provides information about the capabilities of the immersive headset worn by the player. Qui viene illustrato come usare il valore predefinito SpatialLocator.Here, we show how to use the default SpatialLocator.

Il localizzatore spaziale rappresenta il dispositivo di realtà mista di Windows e tiene traccia del movimento del dispositivo e fornisce sistemi di coordinate che possono essere riconosciuti in relazione alla relativa posizione.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.

Da AppMain:: OnHolographicDisplayIsAvailableChanged:From AppMain::OnHolographicDisplayIsAvailableChanged:

spatialLocator = SpatialLocator::GetDefault();

Creare il frame di riferimento fisso una volta all'avvio dell'app.Create the stationary reference frame once when the app is launched. Questo è analogo alla definizione di un sistema di coordinate globale, con l'origine posizionata in corrispondenza della posizione del dispositivo all'avvio dell'app.This is analogous to defining a world coordinate system, with the origin placed at the device's position when the app is launched. Questo frame di riferimento non si sposta con il dispositivo.This reference frame doesn't move with the device.

Da AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

m_stationaryReferenceFrame =
    m_spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

Tutti i frame di riferimento sono allineati alla gravità, ovvero l'asse y punta "verso l'alto" in relazione all'ambiente dell'utente.All reference frames are gravity aligned, meaning that the y-axis points "up" in relation to the user's environment. Poiché Windows utilizza i sistemi di coordinate "di destra", la direzione dell'asse – z coincide con la direzione "Avanti" del dispositivo quando viene creato il frame di riferimento.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.

Nota

Quando l'app richiede un posizionamento preciso dei singoli ologrammi, usare un SpatialAnchor per ancorare il singolo ologramma a una posizione nel mondo reale.When your app requires precise placement of individual holograms, use a SpatialAnchor to anchor the individual hologram to a position in the real world. Ad esempio, usare un ancoraggio spaziale quando l'utente indica un punto di interesse speciale.For example, use a spatial anchor when the user indicates a point to be of special interest. Le posizioni di ancoraggio non sono derivate, ma possono essere modificate.Anchor positions do not drift, but they can be adjusted. Per impostazione predefinita, quando si modifica un ancoraggio, la posizione viene semplificata al posto dei diversi frame successivi dopo la correzione.By default, when an anchor is adjusted, it eases its position into place over the next several frames after the correction has occurred. A seconda dell'applicazione, in questo caso si potrebbe voler gestire la regolazione in modo diverso, ad esempio rinviando l'ologramma al di fuori della visualizzazione.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). La proprietà RawCoordinateSystem e gli eventi RawCoordinateSystemAdjusted abilitano queste personalizzazioni.The RawCoordinateSystem property and RawCoordinateSystemAdjusted events enable these customizations.

Risposta agli eventi locatability modificatiRespond to locatability changed events

Il rendering di ologrammi con blocco universale richiede che il dispositivo si trovi nel mondo.Rendering world-locked holograms requires the device to locate itself in the world. Questo potrebbe non essere sempre possibile a causa di condizioni ambientali e, in tal caso, l'utente può prevedere un'indicazione visiva dell'interruzione del rilevamento.This may not always be possible because of environmental conditions, and if so, the user may expect a visual indication of the tracking interruption. È necessario eseguire il rendering di questa indicazione visiva usando i frame di riferimento collegati al dispositivo, anziché stazionari al mondo.This visual indication must be rendered using reference frames attached to the device, instead of stationary to the world.

L'app può richiedere di ricevere una notifica in caso di interruzione del rilevamento per qualsiasi motivo.Your app can request to be notified if tracking is interrupted for any reason. Eseguire la registrazione per l'evento LocatabilityChanged per rilevare quando la capacità del dispositivo di individuarsi nel mondo cambia.Register for the LocatabilityChanged event to detect when the device's ability to locate itself in the world changes. Da AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

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

Usare quindi questo evento per determinare quando gli ologrammi non possono essere resi stazionari al mondo.Then use this event to determine when holograms cannot be rendered stationary to the world.

Vedere ancheSee also