En esta página

View3D QML Type

Proporciona una ventana de visualización en la que se representa una escena 3D. Más...

Import Statement: import QtQuick3D
Inherits:

Item

Propiedades

Métodos

  • pickResult closestPointPick(vector3d origin, float radius, Model model) (since 6.11)
  • vector3d mapFrom3DScene(vector3d scenePos)
  • vector3d mapTo3DScene(vector3d viewPos)
  • pickResult pick(float x, float y)
  • pickResult pick(float x, float y, Model model) (since 6.8)
  • List<pickResult> pickAll(float x, float y) (since 6.2)
  • list<Object3D> pickInRect(point start, point end) (since 6.11)
  • List<pickResult> pickSubset(float x, float y, list<Model> models) (since 6.8)
  • pickResult rayPick(vector3d origin, vector3d direction) (since 6.2)
  • pickResult rayPick(vector3d origin, vector3d direction, Model model) (since 6.11)
  • List<pickResult> rayPickAll(vector3d origin, vector3d direction) (since 6.2)
  • void setTouchpoint(Item target, point position, int pointId, bool pressed) (since 6.8)

Descripción detallada

View3D proporciona una superficie 2D sobre la que se puede renderizar una escena 3D. Esta superficie es un objeto « Qt Quick » ( Item ) y se puede colocar en una escena « Qt Quick ».

Hay dos formas de definir la escena 3D que se visualiza en View3D: si se define directamente una jerarquía de elementos Node-based como hijos de View3D, esta se convertirá en la escena implícita de View3D.

También es posible hacer referencia a una escena existente utilizando la propiedad « importScene » y asignándole el elemento raíz « Node » de la escena que se desea visualizar. Este « Node » no tiene por qué ser un antecesor del View3D, y se pueden tener varios View3D que importen la misma escena.

Esto se muestra en el ejemplo de View3D.

Si el View3D tiene un elemento hijo Nodes y la propiedad importScene está establecida al mismo tiempo, ambas escenas se renderizarán como si fueran subárboles hermanos dentro de la misma escena.

Para controlar cómo se renderiza una escena, puedes establecer la propiedad ` environment `. El tipo ` SceneEnvironment ` tiene varias propiedades visuales que se pueden ajustar, como el color de fondo, el mapeo de tonos, el suavizado y otras. ` ExtendedSceneEnvironment `, en el módulo ` QtQuick3D.Helpers `, amplía ` SceneEnvironment ` con aún más funciones, añadiendo efectos comunes de posprocesamiento.

Además, para que se pueda renderizar cualquier elemento en View3D, la escena necesita una Camera. Si solo hay una Camera en la escena, esta se seleccionará automáticamente. De lo contrario, se puede utilizar la propiedad camera para seleccionar la cámara. La Camera determina qué partes de la escena son visibles y cómo se proyectan sobre la superficie 2D.

Por defecto, la escena 3D se renderizará primero en un búfer fuera de pantalla y, una vez finalizado, se compondrá con el resto de la escena Qt Quick. Esto proporciona el máximo nivel de compatibilidad, pero puede afectar al rendimiento en algunos equipos gráficos. Si este es el caso, se puede utilizar la propiedad renderMode para cambiar la forma en que se renderiza el View3D en la ventana.

Un View3D con el renderMode predeterminado «Offscreen» es, implícitamente, también un texture provider. Esto significa que ShaderEffect o Texture.sourceItem pueden hacer referencia directamente al View3D siempre que todos los elementos se encuentren dentro del mismo window. Al igual que con cualquier otro Item, también es posible cambiar el View3D, o uno de sus antecesores, a un item layer basado en texturas.

Véase también el ejemplo de View3D enQt Quick 3D.

Documentación de propiedades

camera : QtQuick3D::Camera

Esta propiedad especifica qué cámara Camera se utiliza para renderizar la escena. Si no se configura esta propiedad, se utilizará la primera cámara habilitada de la escena.

Nota: Se recomienda encarecidamente establecer esta propiedad de forma explícita en lugar de confiar en la selección automática de la cámara. Cuando hay varias cámaras en la escena, la selección automática no garantiza qué cámara se elegirá. Cuando se utilizan « layers », especificar la cámara de forma explícita también evita una reevaluación innecesaria de los nodos de la escena.

Nota: Si esta propiedad contiene una cámara que no es « visible », no se realizarán más intentos para encontrar una cámara.

Véase también « PerspectiveCamera », « OrthographicCamera », « FrustumCamera » y « CustomCamera ».

effectiveTextureSize : size [since 6.7]

Esta propiedad muestra el tamaño, en píxeles, de los búferes de color (y de profundidad/plantilla) subyacentes. Está pensada para utilizarse en el hilo de la interfaz gráfica de usuario (principal), en enlaces QML o en JavaScript.

Se trata de una propiedad de solo lectura.

Nota: Esta propiedad solo es relevante cuando « renderMode » está establecido en « Offscreen ».

Esta propiedad se introdujo en Qt 6.7.

Véase también « explicitTextureWidth », « explicitTextureHeight » y « DebugView ».

environment : QtQuick3D::SceneEnvironment

Esta propiedad especifica el SceneEnvironment utilizado para renderizar la escena.

Nota: Si se establece esta propiedad en « null », se restablecerá el « SceneEnvironment » a su valor por defecto.

Véase también « SceneEnvironment ».

explicitTextureHeight : int [since 6.7]

La altura, en píxeles, de la textura asociada al elemento. Es relevante cuando se desea un tamaño fijo para la textura que no dependa del tamaño del elemento. Este tamaño no afecta a la geometría del elemento (su tamaño y ubicación dentro de la escena), lo que significa que el contenido de la textura aparecerá ampliado o reducido (y posiblemente estirado) en el área del elemento.

Por defecto, el valor es 0. Un valor de 0 significa que el tamaño de la textura se adapta al tamaño del elemento. (texture size in pixels = item's logical size * device pixel ratio).

Nota: Esta propiedad solo es relevante cuando renderMode está establecido en Offscreen. En caso contrario, se ignora su valor.

Esta propiedad se introdujo en Qt 6.7.

Véase también explicitTextureWidth, effectiveTextureSize y DebugView.

explicitTextureWidth : int [since 6.7]

El ancho, en píxeles, de la textura asociada al elemento. Es relevante cuando se desea un tamaño fijo para la textura que no dependa del tamaño del elemento. Este tamaño no afecta a la geometría del elemento (su tamaño y ubicación dentro de la escena), lo que significa que el contenido de la textura aparecerá ampliado o reducido (y posiblemente distorsionado) en el área del elemento.

Por defecto, el valor es 0. Un valor de 0 significa que el tamaño de la textura se adapta al tamaño del elemento. (texture size in pixels = item's logical size * device pixel ratio).

Nota: Esta propiedad solo es relevante cuando renderMode está establecido en Offscreen. De lo contrario, se ignora su valor.

Esta propiedad se introdujo en Qt 6.7.

Véase también explicitTextureHeight, effectiveTextureSize y DebugView.

extensions : List<QtQuick3D::Object3D>

Esta propiedad contiene una lista de extensiones de usuario que deben utilizarse con este View3D.

Véase también RenderExtension.

importScene : QtQuick3D::Node

Esta propiedad define el nodo de referencia de la escena que se va a renderizar en la ventana gráfica. No es necesario que el nodo sea un nodo secundario de « View3D ». Este nodo de referencia pasa a ser un nodo hermano de los nodos secundarios de « View3D », si los hay.

Nota: Las escenas solo se pueden compartir entre elementos « View3D » que se encuentren en el mismo « window ».

Nota: Al compartir escenas entre varios elementos « View3D », la escena importada debe importarse en su totalidad; es decir, no se admite la importación de un subárbol de una escena. Si es necesario que varios «View3D» muestren diferentes partes de la misma escena compartida, se recomienda utilizar « layers » en su lugar.

Nota: Esta propiedad solo se puede configurar una vez; los cambios posteriores no tendrán ningún efecto.

También puede definir directamente una jerarquía de elementos « Node-based » como hijos del « View3D »; de este modo, esta se convertirá en la escena implícita del « View3D ».

Para obtener la escena actual de View3D, utiliza la propiedad scene.

Véase también Node.

renderFormat : enumeration [since 6.4]

Esta propiedad determina el formato de la textura de fondo. Solo es aplicable cuando el « View3D » se representa en una textura, por ejemplo, porque el « renderMode » es « View3D.Offscreen ».

El valor predeterminado es « ShaderEffectSource.RGBA8 ».

Si el controlador gráfico subyacente no admite el formato en tiempo de ejecución, se utiliza RGBA8.

Esta propiedad se introdujo en Qt 6.4.

Véase también QtQuick::ShaderEffectSource::format y QtQuick::Item::layer.format.

renderMode : enumeration

Esta propiedad determina cómo se combina el « View3D » con el resto de elementos de la escena « Qt Quick ».

Por defecto, la escena se renderizará en un búfer fuera de pantalla como paso intermedio. A continuación, este búfer fuera de pantalla se renderiza en la ventana (o destino de renderizado) como cualquier otro Qt Quick Item .

Para la mayoría de los usuarios, no será necesario cambiar el modo de renderizado, por lo que esta propiedad puede ignorarse sin problema. Sin embargo, en algunos equipos gráficos, el uso de un búfer fuera de pantalla puede suponer un cuello de botella en el rendimiento. Si este es el caso, podría merecer la pena probar otros modos.

ConstanteDescripción
View3D.OffscreenLa escena se renderiza en un búfer fuera de pantalla como paso intermedio. A continuación, este búfer fuera de pantalla se combina con el resto de la escena Qt Quick.
View3D.UnderlayLa escena se renderiza directamente en la ventana antes de que se renderice el resto de la escena de « Qt Quick ». Con este modo, el « View3D » no puede colocarse encima de otros elementos de « Qt Quick ».
View3D.OverlayLa escena se renderiza directamente en la ventana una vez renderizado « Qt Quick ». Con este modo, « View3D » siempre aparecerá encima de otros elementos de « Qt Quick ».
View3D.InlineEl grafo de escena de « View3D » se integra en el grafo de escena principal, y se aplica la misma semántica de ordenación que a cualquier otro elemento « Qt Quick » de « Item ». Dado que este modo puede dar lugar a problemas sutiles, dependiendo del contenido de la escena, debido a la inserción de contenido 3D basado en la profundidad en un grafo de escena 2D, no se recomienda su uso, a menos que surja una necesidad específica.

El valor por defecto es View3D.Offscreen.

Nota: Al cambiar el modo de renderizado, es importante tener en cuenta que « View3D.Offscreen » (el valor por defecto) es el único modo que garantiza una fidelidad gráfica perfecta. El resto de modos presentan limitaciones que pueden provocar fallos visuales, por lo que es importante comprobar que el resultado visual sigue siendo correcto al modificar esta propiedad.

Nota: Al utilizar los modos «Underlay», «Overlay» o «Inline», puede resultar útil —y, en algunos casos, necesario— desactivar las escrituras en el búfer de profundidad del grafo de escena de « Qt Quick » mediante ` QQuickGraphicsConfiguration::setDepthBufferFor2D()` antes de mostrar el ` QQuickWindow ` o el ` QQuickView ` que aloja el elemento ` View3D `.

renderOverrides : enumeration

Determina cómo realiza el renderizado el Qt Quick 3D.

ConstanteDescripción
View3D.NoneEl renderizado se lleva a cabo con normalidad. Las pasadas internas se programan según lo requieran las funciones utilizadas en la aplicación.
View3D.DisableInternalPassesDesactiva las pasadas de renderizado internas de « Qt Quick 3D». Cuando se establece este modo, la aplicación se encarga de generar y presentar el fotograma final. Normalmente, esto implica implementar pasadas de usuario personalizadas y presentar el resultado en la ventana gráfica mediante « SimpleQuadRenderer » o un « render extension » personalizado.

renderStats : QtQuick3D::RenderStats [read-only]

Esta propiedad proporciona estadísticas sobre la representación de un fotograma, tales como fps, frameTime, renderTime, syncTime y maxFrameTime.

scene : QtQuick3D::Node [read-only]

Devuelve el objeto raíz « Node » de la escena de « View3D ».

Para definir la escena 3D que se visualiza en el View3D:

  • Define una jerarquía de elementos « Node-based » como hijos directos del « View3D »; de este modo, esta se convertirá en la escena implícita del « View3D ».
  • Haz referencia a una escena existente utilizando la propiedad « importScene » y establécela en el « Node » raíz de la escena que desees visualizar. Este « Node » no tiene por qué ser un antecesor del « View3D », y puedes tener varios «View3D» que importen la misma escena.

Véase también importScene.

Documentación del método

[since 6.11] pickResult closestPointPick(vector3d origin, float radius, Model model)

Este método buscará el punto de la superficie de model que se encuentre más cerca de origin, dentro de una distancia de radius. Si model es null, se buscará el objeto más cercano dentro de radius.

Si no existe ningún objeto de este tipo, se devuelve null.

Este método se introdujo en Qt 6.11.

vector3d mapFrom3DScene(vector3d scenePos)

Transforma « scenePos » del espacio de la escena (3D) al espacio de la vista (2D).

Los valores x e y devueltos estarán en coordenadas de vista, con la esquina superior izquierda en [0, 0] y la esquina inferior derecha en [anchura, altura]. El valor z devuelto contiene la distancia desde el plano de recorte cercano del frustum (clipNear) hasta scenePos en coordenadas de escena. Si la distancia es negativa, significa que scenePos se encuentra detrás de la cámara activa. Si scenePos no se puede asignar a una posición en la escena, se devuelve la posición [0, 0, 0].

Esta función requiere que se haya asignado ` camera ` a la vista.

Véanse también mapTo3DScene() y Camera.mapToViewport().

vector3d mapTo3DScene(vector3d viewPos)

Transforma viewPos del espacio de vista (2D) al espacio de escena (3D).

Los valores x e y de ` viewPos ` deben estar en coordenadas de vista, con la esquina superior izquierda en [0, 0] y la esquina inferior derecha en [anchura, altura]. El valor z se interpreta como la distancia desde el plano de recorte cercano del frustum (clipNear) en coordenadas de escena.

Si no es posible asignar correctamente « viewPos » a una posición en la escena, se devuelve la posición [0, 0, 0].

Esta función requiere que se haya asignado un ` camera ` a la vista.

Véanse también mapFrom3DScene() y Camera.mapFromViewport().

pickResult pick(float x, float y)

Este método «lanzará» un rayo hacia la escena desde las coordenadas de la vista x y y y devolverá información sobre la intersección más cercana con un objeto de la escena.

Esto puede, por ejemplo, invocarse con las coordenadas del ratón para encontrar el objeto situado bajo el cursor del ratón.

Los triángulos que el material cull mode descarta al renderizar tampoco se seleccionan, por lo que solo se informa de la geometría que es realmente visible a lo largo del rayo.

Véanse también pickAll(), pickSubset() y pickInRect().

[since 6.8] pickResult pick(float x, float y, Model model)

Este método «lanzará» un rayo hacia la escena desde las coordenadas de la vista x y y, y devolverá información sobre la intersección entre el rayo y el objeto especificado model.

Esto puede, por ejemplo, invocarse con las coordenadas del ratón para encontrar el objeto situado bajo el cursor del ratón.

Este método se introdujo en Qt 6.8.

Véanse también pickAll(), pickSubset() y pickInRect().

[since 6.2] List<pickResult> pickAll(float x, float y)

Este método «lanzará» un rayo hacia la escena desde las coordenadas de vista x y y y devolverá una lista con información sobre las intersecciones con los objetos de la escena. La lista devuelta está ordenada por distancia desde la cámara, apareciendo primero las intersecciones más cercanas y en último lugar las más lejanas.

Esto puede, por ejemplo, invocarse con las coordenadas del ratón para encontrar el objeto situado bajo el cursor del ratón.

Este método se introdujo en Qt 6.2.

Véase también pick(), pickSubset() y pickInRect().

[since 6.11] list<Object3D> pickInRect(point start, point end)

Este método selecciona todos los objetos que se encuentran dentro de una región rectangular definida por los puntos start y end en coordenadas de vista.

Devuelve una lista de los objetos que se encuentran dentro del rectángulo especificado. Esto puede utilizarse para la selección de área, en la que el usuario arrastra un rectángulo para seleccionar varios objetos.

Este método se introdujo en Qt 6.11.

Véanse también pick(), pickAll() y pickSubset().

[since 6.8] List<pickResult> pickSubset(float x, float y, list<Model> models)

Este método «lanzará» un rayo hacia la escena desde las coordenadas de la vista x y y y devolverá información sobre las intersecciones con la lista pasada models. Solo se comprobará con respecto a la lista de modelos pasada. La lista devuelta está ordenada por distancia desde la cámara, apareciendo primero las intersecciones más cercanas y en último lugar las más lejanas.

Esto puede, por ejemplo, invocarse con las coordenadas del ratón para encontrar el objeto situado bajo el cursor del ratón.

Funciona tanto con la propiedad `list<Model>` como con matrices dinámicas de modelos en JavaScript.

Este método se introdujo en Qt 6.8.

Véase también pick(), pickAll() y pickInRect().

[since 6.2] pickResult rayPick(vector3d origin, vector3d direction)

Este método «lanzará» un rayo hacia la escena, partiendo de origin y en direction, y devolverá información sobre la intersección más cercana con un objeto de la escena.

Esto puede, por ejemplo, invocarse con la posición y el vector de avance de cualquier objeto de una escena para ver qué objeto se encuentra delante de un elemento. Esto permite realizar la selección desde cualquier punto de la escena.

Los triángulos que el material descarta en cull mode durante el renderizado tampoco se seleccionan, por lo que solo se informa de la geometría que es realmente visible a lo largo del rayo.

Este método se introdujo en Qt 6.2.

[since 6.11] pickResult rayPick(vector3d origin, vector3d direction, Model model)

Este método «lanzará» un rayo hacia la escena partiendo de origin y en direction, y devolverá información sobre la intersección entre el rayo y el model especificado.

Este método se introdujo en Qt 6.11.

[since 6.2] List<pickResult> rayPickAll(vector3d origin, vector3d direction)

Este método «lanzará» un rayo hacia la escena partiendo de origin y en direction, y devolverá una lista con información sobre las intersecciones más cercanas con los objetos de la escena. La lista está ordenada previamente por distancia desde el origen a lo largo del vector de dirección, de modo que las intersecciones más cercanas aparecen en primer lugar y las más lejanas, en último lugar.

Esto permite, por ejemplo, invocar el método con la posición y el vector de avance de cualquier objeto de una escena para ver qué objetos se encuentran delante de un elemento. De este modo, es posible realizar la selección desde cualquier punto de la escena.

Este método se introdujo en Qt 6.2.

[since 6.8] void setTouchpoint(Item target, point position, int pointId, bool pressed)

Envía un evento táctil sintético a target, desplazando el punto táctil con el ID pointId a position, y utilizando pressed para determinar si el punto está pulsado. También envía el evento de liberación táctil correspondiente si pointId estaba activo previamente en otro elemento.

Este método se introdujo en Qt 6.8.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.