Obtención de HolographicSpaceGetting a HolographicSpace

Nota

Este artículo está relacionado con las API nativas de WinRT heredadas.This article relates to the legacy WinRT native APIs. En el caso de los nuevos proyectos de aplicaciones nativas, se recomienda usar la API de OpenXR.For new native app projects, we recommend using the OpenXR API.

La clase HolographicSpace es su portal en el mundo holográfica.The HolographicSpace class is your portal into the holographic world. Controla la representación envolvente, proporciona datos de la cámara y proporciona acceso a las API de razonamiento espacial.It controls immersive rendering, provides camera data, and provides access to spatial reasoning APIs. Creará una para el identificador de usuario de la aplicación de UWP o la aplicación Win32.You'll create one for your UWP app's CoreWindow or your Win32 app's HWND.

Configuración del espacio holográficaSet up the holographic space

La creación del objeto de espacio holográfica es el primer paso para crear una aplicación de Windows Mixed Reality.Creating the holographic space object is the first step in making your Windows Mixed Reality app. Las aplicaciones tradicionales de Windows se representan en una cadena de intercambio de Direct3D creada para la ventana principal de la vista de la aplicación.Traditional Windows apps render to a Direct3D swap chain created for the core window of their application view. Esta cadena de intercambio se muestra en una pizarra en la interfaz de usuario holográfica.This swap chain is displayed to a slate in the holographic UI. Para hacer que la vista de la aplicación sea holográfica en lugar de una pizarra 2D, cree un espacio holográfica para su ventana principal en lugar de una cadena de intercambio.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 presentación de tramas holográficas creadas por este espacio holográfica coloca la aplicación en el modo de representación de pantalla completa.Presenting holographic frames that are created by this holographic space puts your app into full-screen rendering mode.

En el caso de una aplicación para UWP a partir de la plantilla holográfica DirectX 11 (Windows universal), busque este código en el método SetWindow en 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);

Si va a compilar una aplicación de Win32 a partir del ejemplo de Win32 BasicHologram, consulte App:: CreateWindowAndHolographicSpace para obtener un ejemplo de HWND.If you're building a Win32 app starting from the BasicHologram Win32 sample, look at App::CreateWindowAndHolographicSpace for an HWND example. Después, puede convertirla en un HWND envolvente creando un HolographicSpaceasociado: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 vez que haya obtenido un HolographicSpace para el HWND de UWP o de Win32, el HolographicSpace puede administrar cámaras holográficas, crear sistemas de coordenadas y realizar la representación holográfica.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. El espacio holográfica actual se usa en varios lugares de la plantilla de DirectX:The current holographic space is used in multiple places in the DirectX template:

  • La clase DeviceResources debe obtener cierta información del objeto HolographicSpace para crear el dispositivo Direct3D.The DeviceResources class needs to get some information from the HolographicSpace object to create the Direct3D device. Este es el identificador del adaptador de DXGI asociado a la pantalla holográfica.This is the DXGI adapter ID associated with the holographic display. La clase HolographicSpace usa el dispositivo Direct3D 11 de la aplicación para crear y administrar recursos basados en dispositivos como, por ejemplo, los búferes de reserva de cada cámara holográfica.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. Si le interesa ver lo que hace esta función en el capó, la encontrará en DeviceResources. cpp.If you're interested in seeing what this function does under the hood, you'll find it in DeviceResources.cpp.
  • La función DeviceResources:: InitializeUsingHolographicSpace muestra cómo obtener el adaptador buscando el LUID y cómo elegir un adaptador predeterminado cuando no se especifica ningún adaptador preferido.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 clase principal de la aplicación usa el espacio holográfica de AppView:: SetWindow o App:: CreateWindowAndHolographicSpace para las actualizaciones y la representación.The app's main class uses the holographic space from AppView::SetWindow or App::CreateWindowAndHolographicSpace for updates and rendering.

Nota

Aunque en las secciones siguientes se mencionan los nombres de función de la plantilla como AppView:: SetWindow que suponen que se ha iniciado desde la plantilla de aplicación de UWP de Holographic, los fragmentos de código que se ven se aplicarán igualmente a través de aplicaciones de UWP y 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.

A continuación, profundizaremos en el proceso de configuración que SetHolographicSpace es responsable de en la clase AppMain.Next, we'll dive into the setup process that SetHolographicSpace is responsible for in the AppMain class.

Suscripción a eventos de cámara, creación y eliminación de recursos de cámaraSubscribe to camera events, create, and remove camera resources

El contenido holográfica de la aplicación vive en su espacio holográfica y se ve a través de una o más cámaras holográficas, que representan perspectivas diferentes en la escena.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. Ahora que tiene el espacio holográfica, puede recibir datos para cámaras holográficas.Now that you have the holographic space, you can receive data for holographic cameras.

La aplicación debe responder a los eventos de CameraAdded mediante la creación de los recursos específicos de esa cámara.Your app needs to respond to CameraAdded events by creating any resources that are specific to that camera. Un ejemplo de este tipo de recurso es la vista de destino de representación del búfer de reserva.An example of such a resource is your back buffer render target view. Puede ver este código en la función DeviceResources:: SetHolographicSpace , llamada por AppView:: SetWindow antes de que la aplicación cree cualquier trama holográfica: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));

La aplicación también debe responder a los eventos de CameraRemoved mediante la liberación de los recursos que se crearon para esa cámara.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));

Los controladores de eventos deben completar algún trabajo para que la representación holográfica fluya sin problemas y la aplicación se represente en absoluto.The event handlers must complete some work to keep holographic rendering flowing smoothly, and your app rendering at all. Lea el código y los comentarios de los detalles: puede buscar OnCameraAdded y OnCameraRemoved en la clase principal para entender cómo controla la asignación de m_cameraResources mediante 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.

En este momento, nos centramos en AppMain y en la configuración que permite que la aplicación Conozca las cámaras holográficas.Right now, we're focused on AppMain and the setup that it does to enable your app to know about holographic cameras. Teniendo esto en cuenta, es importante tener en cuenta los dos requisitos siguientes:With this in mind, it's important to take note of the following two requirements:

  1. En el caso del controlador de eventos CameraAdded , la aplicación puede trabajar de forma asincrónica para finalizar la creación de recursos y la carga de recursos para la nueva cámara holográfica.For the CameraAdded event handler, the app can work asynchronously to finish creating resources and loading assets for the new holographic camera. Las aplicaciones que tardan más de un fotograma para completar este trabajo deben solicitar un aplazamiento y completar el aplazamiento después de la carga de forma asincrónica.Apps that take more than one frame to complete this work should request a deferral, and complete the deferral after loading asynchronously. Una tarea PPL se puede usar para realizar el trabajo asincrónico.A PPL task can be used to do asynchronous work. La aplicación debe asegurarse de que esté lista para representarse en esa cámara inmediatamente cuando salga del controlador de eventos o cuando complete el aplazamiento.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. Salir del controlador de eventos o completar el aplazamiento indica al sistema que la aplicación ya está lista para recibir tramas holográficas con esa cámara incluida.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. Cuando la aplicación recibe un evento CameraRemoved , debe liberar todas las referencias al búfer de reserva y salir de la función inmediatamente.When the app receives a CameraRemoved event, it must release all references to the back buffer and exit the function right away. Esto incluye las vistas de destino de representación y cualquier otro recurso que pueda contener una referencia a IDXGIResource.This includes render target views, and any other resource that might hold a reference to the IDXGIResource. La aplicación también debe asegurarse de que el búfer de reserva no está asociado como destino de representación, como se muestra en CameraResources:: ReleaseResourcesForBackBuffer.The app must also ensure that the back buffer isn't attached as a render target, as shown in CameraResources::ReleaseResourcesForBackBuffer. Para ayudar a acelerar las cosas, la aplicación puede liberar el búfer de reserva y, a continuación, iniciar una tarea para completar de forma asincrónica cualquier otro trabajo de anulación de la cámara.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. La plantilla de aplicación holográfica incluye una tarea PPL que puede usar con este fin.The holographic app template includes a PPL task that you can use for this purpose.

Nota

Si desea determinar cuándo se muestra una cámara agregada o quitada en el fotograma, use las propiedades HolographicFrame AddedCameras y RemovedCameras .If you want to determine when an added or removed camera shows up on the frame, use the HolographicFrame AddedCameras and RemovedCameras properties.

Creación de un marco de referencia para el contenido holográficaCreate a frame of reference for your holographic content

El contenido de la aplicación debe colocarse en un sistema de coordenadas espaciales que se va a representar en el HolographicSpace.Your app's content must be positioned in a spatial coordinate system to be rendered in the HolographicSpace. El sistema proporciona dos fotogramas principales de referencia, que puede usar para establecer un sistema de coordenadas para los hologramas.The system provides two primary frames of reference, which you can use to establish a coordinate system for your holograms.

Hay dos tipos de fotogramas de referencia en Windows Holographic: los fotogramas de referencia conectados al dispositivo y hacen referencia a fotogramas que permanecen estacionarios a medida que el dispositivo se mueve por el entorno del usuario.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. De forma predeterminada, la plantilla de aplicación holográfica usa un marco de referencia estacional. Esta es una de las formas más sencillas de representar hologramas de bloque mundial.The holographic app template uses a stationary reference frame by default; this is one of the simplest ways to render world-locked holograms.

Los fotogramas de referencia estacionarios están diseñados para estabilizar las posiciones cerca de la ubicación actual del dispositivo.Stationary reference frames are designed to stabilize positions near the device's current location. Esto significa que las coordenadas más allá del dispositivo pueden desplazarse ligeramente con respecto al entorno del usuario, ya que el dispositivo aprende más sobre el espacio que lo rodea.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. Hay dos maneras de crear un marco estacionario de referencia: adquirir el sistema de coordenadas de la fase espacialo usar el valor predeterminado 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. Si va a crear una aplicación de Windows Mixed Reality para auriculares envolventes, el punto de partida recomendado es la fase espacial.If you're creating a Windows Mixed Reality app for immersive headsets, the recommended starting point is the spatial stage. La fase espacial también proporciona información acerca de las capacidades del casco envolvente que gasta el reproductor.The spatial stage also provides information about the capabilities of the immersive headset worn by the player. Aquí se muestra cómo usar el valor predeterminado de SpatialLocator.Here, we show how to use the default SpatialLocator.

El localizador espacial representa el dispositivo de Windows Mixed Reality y realiza un seguimiento del movimiento del dispositivo y proporciona sistemas de coordenadas que se pueden entender en relación con su ubicación.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.

Desde AppMain:: OnHolographicDisplayIsAvailableChanged:From AppMain::OnHolographicDisplayIsAvailableChanged:

spatialLocator = SpatialLocator::GetDefault();

Cree el marco de referencia estacionario una vez cuando se inicie la aplicación.Create the stationary reference frame once when the app is launched. Esto es análogo a definir un sistema de coordenadas universal, con el origen colocado en la posición del dispositivo cuando se inicia la aplicación.This is analogous to defining a world coordinate system, with the origin placed at the device's position when the app is launched. Este fotograma de referencia no se mueve con el dispositivo.This reference frame doesn't move with the device.

Desde AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

m_stationaryReferenceFrame =
    m_spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

Todos los marcos de referencia están alineados con la gravedad, lo que significa que el eje y apunta "hacia arriba" en relación con el entorno del usuario.All reference frames are gravity aligned, meaning that the y-axis points "up" in relation to the user's environment. Puesto que Windows usa sistemas de coordenadas "zurdos", la dirección del eje – z coincide con la dirección "hacia delante" a la que se enfrenta el dispositivo cuando se crea el fotograma de referencia.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

Cuando la aplicación requiere una ubicación precisa de hologramas individuales, use un SpatialAnchor para anclar el holograma individual en una posición del 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 ejemplo, use un delimitador espacial cuando el usuario indique que un punto debe ser de especial interés.For example, use a spatial anchor when the user indicates a point to be of special interest. Las posiciones de anclaje no se desplazan, pero se pueden ajustar.Anchor positions do not drift, but they can be adjusted. De forma predeterminada, cuando se ajusta un delimitador, facilita su posición en lugar de los próximos fotogramas después de que se haya realizado la corrección.By default, when an anchor is adjusted, it eases its position into place over the next several frames after the correction has occurred. En función de la aplicación, cuando esto sucede, es posible que desee controlar el ajuste de manera diferente (por ejemplo, si lo aplaza hasta que el holograma esté fuera de la vista).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 propiedad RawCoordinateSystem y los eventos RawCoordinateSystemAdjusted habilitan estas personalizaciones.The RawCoordinateSystem property and RawCoordinateSystemAdjusted events enable these customizations.

Responder a los eventos de búsqueda modificadaRespond to locatability changed events

La representación de hologramas con bloqueo mundial requiere que el dispositivo se encuentre en el mundo.Rendering world-locked holograms requires the device to locate itself in the world. Esto puede no ser siempre posible debido a las condiciones del entorno, y si es así, el usuario puede esperar una indicación visual de la interrupción del seguimiento.This may not always be possible because of environmental conditions, and if so, the user may expect a visual indication of the tracking interruption. Esta indicación visual se debe representar mediante fotogramas de referencia conectados al dispositivo, en lugar de separarse del mundo.This visual indication must be rendered using reference frames attached to the device, instead of stationary to the world.

La aplicación puede solicitar recibir una notificación si se interrumpe el seguimiento por cualquier motivo.Your app can request to be notified if tracking is interrupted for any reason. Regístrese en el evento LocatabilityChanged para detectar cuándo cambia la capacidad del dispositivo de localizarse en el mundo.Register for the LocatabilityChanged event to detect when the device's ability to locate itself in the world changes. Desde AppMain:: SetHolographicSpace:From AppMain::SetHolographicSpace:

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

A continuación, use este evento para determinar cuándo no se pueden representar los hologramas estacionales en el mundo.Then use this event to determine when holograms cannot be rendered stationary to the world.

Consulte tambiénSee also