En esta página

Scene3D QML Type

El tipo Scene3D se utiliza para integrar una escena de Qt3D en una escena de QtQuick 2. Más información...

Import Statement: import QtQuick.Scene3D 2.12
Inherits:

Item

Status: Technology preview

Este tipo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.

Propiedades

Métodos

Descripción detallada

El tipo Scene3D representa una escena Qt3D, proporcionada por un objeto « Entity », en un objeto «Framebuffer» con muestreo múltiple. Posteriormente, este objeto se transfiere a un objeto «Framebuffer» sin muestreo múltiple, que a continuación se representa con alfa premultiplicado. Si no se requiere el multimuestreo, se puede evitar estableciendo la propiedad « multisample » en « false ». En este caso, Scene3D renderizará directamente en el objeto Framebuffer sin multimuestreo.

Si la escena que se va a renderizar incluye materiales no opacos, es posible que tengas que modificar dichos materiales con argumentos de mezcla personalizados para que se rendericen correctamente. Por ejemplo, si trabajas con un « PhongAlphaMaterial » y una escena con un color de transparencia opaco, probablemente querrás añadir:

sourceAlphaArg: BlendEquationArguments.Zero
destinationAlphaArg: BlendEquationArguments.One

a ese material.

No se recomienda instanciar más de una instancia de Scene3D por aplicación. El motivo es que una instancia de Scene3D instancia todo el motor de « Qt 3D » (por ejemplo, gestores de memoria, grupo de subprocesos, renderizado) bajo la escena.

Nota: Establecer la visibilidad del elemento Scene3D en «false» detendrá el bucle de simulación de Qt 3D. Esto significa que, si se vincula la propiedad «visible» a una expresión que depende de las actualizaciones de propiedades impulsadas por el bucle de simulación de Qt 3D (FrameAction), dicha expresión nunca se reevaluará.

Documentación de propiedades

aspects : list<string>

La lista de aspectos que deben registrarse para la escena 3D.

Por ejemplo, si la escena utiliza FrameAction, el aspecto « "logic" » debe incluirse en la lista.

El aspecto « "render" » está integrado de forma predeterminada y no es necesario incluirlo explícitamente en la lista.

cameraAspectRatioMode : enumeration

Define cómo se calcula la relación de aspecto de una cámara que se encuentra en la escena.

ConstanteDescripción
Scene3D.AutomaticAspectRatioRelación de aspecto automática.
Scene3D.UserAspectRatioRelación de aspecto definida por el usuario.

compositingMode : enumeration

ConstanteDescripción
FBOLa escena se renderiza en un objeto de búfer de fotogramas (Frame Buffer Object), lo que puede resultar costoso en algunas plataformas y equipos, pero ofrece una mayor flexibilidad. Relación de aspecto automática. Este es el modo de composición que debes elegir si tu elemento « Scene3D » no debe ocupar toda la pantalla y si, opcionalmente, tienes previsto cambiar su tamaño o animarlo. En este modo, la posición de « Scene3D » en el archivo QML controla su orden de superposición con respecto a los demás elementos « Qt Quick ».
UnderlayAdecuado para escenas 3D a pantalla completa en las que el uso de un FBO podría suponer un consumo excesivo de recursos. Scene3D se comporta como una capa subyacente de QtQuick. Ten en cuenta que, al utilizar este modo, se ignoran el tamaño de Scene3D y sus transformaciones, y el renderizado ocupará toda la pantalla. La posición de Scene3D en el archivo QML tampoco tendrá ningún efecto. El contenido de « Qt 3D » se dibujará antes que cualquier contenido de « Qt Quick ». Hay que tener cuidado de no dibujar por encima y ocultar el contenido de « Qt 3D » al superponer el contenido de « Qt Quick ». Además, al utilizar este modo, la propiedad «clearBeforeRendering» de la ventana se establecerá automáticamente en «false».

El valor por defecto es « FBO ».

entity : Entity [default]

La entidad raíz de la escena 3D que se va a mostrar.

hoverEnabled : bool

true si se admiten eventos de desplazamiento del cursor.

multisample : bool

true si se solicita un búfer de renderizado con muestreo múltiple.

Por defecto, el multimuestreo está habilitado. Si la implementación de OpenGL no admite búferes de renderizado multimuestreados ni transferencias de búfer de fotogramas, se ignora la solicitud de utilizar multimuestreo.

Nota: Evita cambiar el valor con frecuencia, ya que implica una inicialización costosa y potencialmente lenta de los búferes de fotogramas y otros recursos de OpenGL.

Documentación del método

void setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)

Establece el área del elemento en area y la relación de píxeles en devicePixelRatio.

© 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.