Obsolete Members for Qt3DRender

Qt3DRender 类的以下成员已被弃用。提供这些成员是为了确保旧源代码能够继续运行。我们强烈建议不要在新代码中使用它们。

命名空间

类

命名空间

[deprecated] namespace Qt3DRender::Quick

该命名空间已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] namespace Qt3DRender::Render

该命名空间已弃用。我们强烈建议不要在新代码中使用它。

类

[deprecated] class Qt3DRender::QAbstractLight

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QAbstractRayCaster

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QAbstractRayCaster 这是一个用于在 3D 场景中进行光线投射的抽象基类。Qt3DRender::QAbstractRayCaster 无法直接实例化，而必须通过其子类进行实例化。QAbstractRayCaster 规定了所有光线投射器的通用属性（例如运行模式和图层处理），而将实际的光线投射细节交由子类处理。

光线投射与拾取（使用Qt3DRender::QObjectPicker ）的不同之处在于，它无需鼠标事件触发。

默认情况下，Qt3DRender::QAbstractRayCaster 的实例处于禁用状态。启用后，系统将在每帧对指定的光线进行检测，以判断是否与对象相交。即使未找到任何对象，QAbstractRayCaster::hits 属性也会根据光线投射的结果进行更新。

Qt3DRender::QPickingSettings 可用于控制光线投射，例如指定要检测的几何体以及结果的返回方式。

此外，Qt3DRender::QLayer 组件可用于控制实体或实体子图对光线投射的响应方式。

另请参阅 Qt3DRender::QRayCaster 、Qt3DRender::QScreenRayCaster 、Qt3DRender::QObjectPicker 、Qt3DRender::QPickingSettings 以及Qt3DRender::QNoPicking 。

[deprecated] class Qt3DRender::QAbstractTexture

该类已弃用。我们强烈建议不要在新代码中使用它。

不应直接使用 QAbstractTexture 类，而应通过其子类之一进行使用。每个子类都实现了一种特定的纹理目标（2D、2DArray、3D、CubeMap 等）。每个子类为每一层、立方体贴图面以及 Mipmap 级别提供一组函子。 随后，后端会使用这些 functor 来将数据正确地填充到相应的 OpenGL 纹理中。期望 functor 尽可能减少处理操作，以免减慢纹理的生成和上传速度。如果纹理的内容是由耗时的过程生成过程产生的，则建议不要直接在 functor 中实现该过程。

所有纹理都是唯一的。如果两次实例化相同的纹理，这将在 GPU 上创建两个完全相同的纹理，不会发生资源共享。

[deprecated] class Qt3DRender::QAbstractTextureImage

该类已弃用。我们强烈建议不要在新代码中使用它。

应使用 QAbstractTextureImage 作为向QAbstractTexture 提供图像数据的手段。它包含必要的信息：MIP 贴图级别、图层、立方体面，并能将数据加载到 OpenGL 纹理的正确位置。

实际数据是通过QTextureImageDataGenerator 提供的，该类将在后端由Aspect任务执行。应通过继承QAbstractTextureImage来提供一个 functor，以及该 functor 加载实际数据所需的其他属性。

[deprecated] class Qt3DRender::QAlphaCoverage

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QAlphaCoverage 类可启用“透明度转覆盖率”多采样模式。启用后，片段透明度值将作为采样的覆盖率，并与片段覆盖率值相结合。若多采样功能被禁用，Qt3DRender::QAlphaCoverage 将不执行任何操作。“透明度转覆盖率”模式在需要顺序无关混合时最为有用，例如渲染树叶、草丛及其他茂密的植被时。

可通过调用QRenderPass::addRenderState() 将其添加到QRenderPass 中：

QRenderPass *renderPass = new QRenderPass();

// Create a alpha coverage render state
QAlphaCoverage *alphaCoverage = new QAlphaCoverage();
QMultiSampleAntiAliasing *multiSampleAntialiasing = new QMultiSampleAntiAliasing();

// Add the render states to the render pass
renderPass->addRenderState(alphaCoverage);
renderPass->addRenderState(multiSampleAntialiasing);

或者通过调用QRenderStateSet::addRenderState() 将其添加到QRenderStateSet 中：

QRenderStateSet *renderStateSet = new QRenderStateSet();

// Create a alpha coverage render state
QAlphaCoverage *alphaCoverage = new QAlphaCoverage();
QMultiSampleAntiAliasing *multiSampleAntialiasing = new QMultiSampleAntiAliasing();

// Add the render states to the render state set
renderStateSet->addRenderState(alphaCoverage);
renderStateSet->addRenderState(multiSampleAntialiasing);

另请参阅 Qt3DRender::QMultiSampleAntiAliasing 。

[deprecated] class Qt3DRender::QAlphaTest

该类已弃用。我们强烈建议不要在新代码中使用它。

正如 OpenGL 文档所解释的：Alpha 测试会根据传入片段的 Alpha 值与一个常量参考值之间的比较结果，有条件地丢弃该片段。

[deprecated] class Qt3DRender::QBlendEquation

该类已被弃用。我们强烈建议不要在新代码中使用它。

混合方程用于确定新像素应如何与帧缓冲区中已有的像素进行混合。

[deprecated] class Qt3DRender::QBlendEquationArguments

该类已弃用。我们强烈建议不要在新代码中使用它。

OpenGL 3.0 之前：为所有绘制缓冲区设置相同的混合状态（一个 QBlendEquationArguments）。OpenGL 3.0-pre4.0： 为所有绘制缓冲区设置相同的混合状态，但可以针对特定缓冲区禁用混合（一个 QBlendEquationArguments 用于设置 glBlendFunc，n 个 QBlendEquationArguments 用于启用/禁用绘制缓冲区） OpenGL 4.0 及以上版本：可以为每个绘制缓冲区单独设置混合状态。

[deprecated] class Qt3DRender::QBlitFramebuffer

该类已弃用。我们强烈建议不要在新代码中使用它。

该节点将一个 `glBlitFrameBuffer ` 或其等效对象插入到命令流中。与绘制带纹理的四边形相比，这为在纹理或由 `QRenderTarget ` 封装的表面后缓冲区之间复制矩形提供了一种更高效的方法。它还支持使用指定的插值方法进行缩放。

[deprecated] class Qt3DRender::QBufferCapture

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QCamera

该类已被弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QCameraLens

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QCameraSelector

该类已弃用。我们强烈建议不要在新代码中使用它。

可以使用 `Qt3DRender::QCameraSelector ` 来选择摄像机，FrameGraph 在绘制实体时会使用该摄像机。

[deprecated] class Qt3DRender::QClearBuffers

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QClearBuffers 的 FrameGraph 节点支持使用特定值清空特定的渲染目标缓冲区。

[deprecated] class Qt3DRender::QClipPlane

该类已弃用。我们强烈建议不要在新代码中使用它。

默认情况下，OpenGL 最多支持 8 个额外的裁剪平面。 Qt3DCore::QClipPlane 允许启用其中一个额外剪裁平面。随后可在着色器中通过 gl_ClipDistance[i] 对这些平面进行操作，其中 i 的取值范围为 0 到 7。底层实现可能支持超过 8 个剪裁平面，但无法保证。

[deprecated] class Qt3DRender::QColorMask

该类已被废弃。我们强烈建议不要在新代码中使用它。

默认情况下，每个颜色分量（红、绿、蓝、透明度）的属性均设置为true ，这意味着它们将被写入帧缓冲区。将任何颜色分量设置为false ，将阻止其被写入帧缓冲区。

[deprecated] class Qt3DRender::QComputeCommand

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QComputeCommand 用于向计算着色器分发工作任务。计算着色器在与 QComputeCommand 添加到同一实体的QMaterial 组件中进行指定。workGroupX 、workGroupY 和workGroupZ 属性分别指定了计算着色器调用时的工作组大小。FrameGraph 中必须存在Qt3DRender::QDispatchCompute 节点，才能实际发出这些命令。

[deprecated] class Qt3DRender::QCullFace

该类已弃用。我们强烈建议不要在新代码中使用它。

QCullFace 用于设置是剔除前侧还是后侧的面。面包括三角形、四边形、多边形和矩形。

可以通过在QRenderPass 上调用addRenderState()方法来添加：

// using namespace Qt3DRender;

QRenderPass *renderPass = new QRenderPass();

// Create a front face culling render state
QCullFace *cullFront = new QCullFace();
cullFront->setMode(QCullFace::Front);

// Add the render state to the render pass
renderPass->addRenderState(cullFront);

或者通过在 `QRenderStateSet` 上调用 `addRenderState()` 方法来添加：

// using namespace Qt3DRender;

QRenderStateSet *renderStateSet = new QRenderStateSet();

// Create a front face culling render state
QCullFace *cullFront = new QCullFace();
cullFront->setMode(QCullFace::Front);

// Add the render state to the render pass
renderStateSet->addRenderState(cullFront);

另请参阅 QFrontFace 。

[deprecated] class Qt3DRender::QDebugOverlay

该类已弃用。我们强烈建议不要在新代码中使用它。

在自定义帧图的一个分支中放置一个 QDebugOverlay 对象，将导致一个包含场景详细信息的叠加层与场景一同渲染。

标准的 QForwardRenderer 包含一个 QDebugOverlay 节点，可通过 QForwardRenderer::showDebugOverlay 属性启用该节点。

[deprecated] class Qt3DRender::QDepthRange

该类已弃用。我们强烈建议不要在新的代码中使用它。

默认情况下，OpenGL 会将场景的深度信息写入深度缓冲区，其取值范围为 [0.0, 1.0]，其中 0.0 对应近裁剪平面，1.0 对应远裁剪平面。 QDepthRange 允许将这些值映射到不同的范围，从而确保场景的某些部分始终渲染在其他部分的前面或后面。近裁剪平面和远裁剪平面的有效值范围均为 0 到 1。

[deprecated] class Qt3DRender::QDepthTest

该类已弃用。我们强烈建议不要在新代码中使用它。

QDepthTest 类用于通过指定的深度测试函数启用深度测试。深度测试可在测试通过时写入片段颜色值，并拒绝测试失败的片段。 深度测试使用深度函数将片段的深度值与 z 缓冲区中的值进行比较。如果底层表面没有 z 缓冲区，则 QDepthTest 不会执行任何操作。

另请参阅 QAlphaTest 和QStencilTest 。

[deprecated] class Qt3DRender::QDirectionalLight

该类已弃用。我们强烈建议不要在新代码中使用它。

定向光是一种行为类似于阳光的光源。无论场景中物体位于何处，定向光发出的光都会从同一方向以相同强度照射到所有物体上。

[deprecated] class Qt3DRender::QDispatchCompute

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QDispatchCompute 允许向计算着色器分发工作任务，以便其在 GPU 上运行。workGroupX 、workGroupY 和workGroupZ 属性用于指定计算着色器调用时的工作组大小。需要向实体添加QComputeCommand 组件，以指示 Qt3D 从实体中选择材质和几何体用于计算调用。 着色器调用的工作组大小将为 QDispatchCompute 和QComputeCommand 中指定的工作组大小的最大值。

[deprecated] class Qt3DRender::QDithering

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QDithering 类用于启用抖动。抖动通过在颜色值中添加噪声来随机化量化误差，从而防止最终图像中出现大面积的图案，例如色带。在渲染到颜色位深度较低的表面（例如 RGB565 或 RGBA4444）时，抖动最为有用。

[deprecated] class Qt3DRender::QEffect

该类已弃用。我们强烈建议不要在新代码中使用它。

QEffect 类整合了一组技术及其相关参数，用于为材质生成渲染效果。

在可能的情况下，一个 QEffect 实例应由多个QMaterial 实例共享。

QEffect *effect = new QEffect();

// Create technique, render pass and shader
QTechnique *gl3Technique = new QTechnique();
QRenderPass *gl3Pass = new QRenderPass();
QShaderProgram *glShader = new QShaderProgram();

// Set the shader on the render pass
gl3Pass->setShaderProgram(glShader);

// Add the pass to the technique
gl3Technique->addRenderPass(gl3Pass);

// Set the targeted GL version for the technique
gl3Technique->graphicsApiFilter()->setApi(QGraphicsApiFilter::OpenGL);
gl3Technique->graphicsApiFilter()->setMajorVersion(3);
gl3Technique->graphicsApiFilter()->setMinorVersion(1);
gl3Technique->graphicsApiFilter()->setProfile(QGraphicsApiFilter::CoreProfile);

// Add the technique to the effect
effect->addTechnique(gl3Technique);

在 QEffect 上定义的QParameter 将覆盖在QTechnique 和QRenderPass 中定义的（同名）参数，但会被QRenderPassFilter 、QTechniqueFilter 和QMaterial 中的参数覆盖。

另请参阅 QMaterial 、QTechnique 以及QParameter 。

[deprecated] class Qt3DRender::QEnvironmentLight

该类已弃用。我们强烈建议不要在新代码中使用它。

QEnvironmentLight 使用立方贴图来实现基于图像的照明（IBL），这是一种常与基于物理的渲染（PBR）结合使用的技术。 立方贴图通常基于高动态范围（HDR）图像，并采用合适的 OpenGL 格式（如 RGBA16F），以处理更宽的数值范围。

有多种工具可用于生成 QEnvironmentLight 所需的立方贴图。例如：

• cmftStudio
• IBLBaker
• Lys

HDRI Haven提供了许多 CC0 许可的 HDR 图像，可作为上述工具的源素材。

[deprecated] class Qt3DRender::QFilterKey

该类已弃用。我们强烈建议不要在新代码中使用它。

QTechnique 和QRenderPass 使用过滤器键来指定在渲染的哪个阶段使用该技术或渲染通道。

[deprecated] class Qt3DRender::QFrameGraphNode

该类已弃用。我们强烈建议不要在新代码中使用它。

由于该类未提供任何与帧图相关的特定行为，因此很少被直接实例化，尽管在动态帧图中将其用于将其他节点分组可能比较方便。其实际行为由子类提供。

其子类包括：

[deprecated] class Qt3DRender::QFrontFace

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QFrontFace 用于设置朝向前方的多边形的绕行方向。

另请参阅 QCullFace 。

[deprecated] class Qt3DRender::QFrustumCulling

该类已弃用。我们强烈建议在新代码中不要使用它。

QFrustumCulling 类可根据摄像机视角及可绘制实体的 QGeometry 边界，对可绘制实体进行视锥体剔除。如果 FrameGraph 中存在 QFrustumCulling，则仅绘制那些 QGeometry 边界与摄像机视锥体（即摄像机视角）相交的实体。 如果不存在 QFrustumCulling，则所有可绘制实体都会被绘制。摄像机由当前层级结构中的QCameraSelector 帧图节点选定。当渲染场景较为复杂时，视锥体剔除可以节省大量 GPU 处理时间。

另请参阅 QCameraSelector 。

[deprecated] class Qt3DRender::QGeometryRenderer

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QGeometryRenderer 包含绘制Qt3DCore::QGeometry 所需的所有信息。QGeometry 存储几何数据的坐标，而 QGeometryRenderer 则指定如何解释这些数据。

[deprecated] class Qt3DRender::QGraphicsApiFilter

该类已弃用。我们强烈建议不要在新的代码中使用它。

[deprecated] class Qt3DRender::QLayer

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QLayer 该类需与 FrameGraph 中的Qt3DRender::QLayerFilter 配合使用。

通过将 recursive 属性设置为 true，可以将 QLayer 应用于实体的子树。

 #include <Qt3DCore/QEntity>
 #include <Qt3DRender/QGeometryRenderer>
 #include <Qt3DRender/QLayer>
 #include <Qt3DRender/QLayerFilter>
 #include <Qt3DRender/QViewport>

// Scene
Qt3DCore::QEntity *rootEntity = new Qt3DCore::Qt3DCore::QEntity;

Qt3DCore::QEntity *renderableEntity = new Qt3DCore::Qt3DCore::QEntity(rootEntity);
Qt3DRender::QGeometryRenderer *geometryRenderer = new Qt3DCore::QGeometryRenderer(renderableEntity);
Qt3DRender::QLayer *layer1 = new Qt3DCore::QLayer(renderableEntity);
layer1->setRecursive(true);
renderableEntity->addComponent(geometryRenderer);
renderableEntity->addComponent(layer1);

...

// FrameGraph
Qt3DRender::QViewport *viewport = new Qt3DRender::QViewport;
Qt3DRender::QLayerFilter *layerFilter = new Qt3DRender::QLayerFilter(viewport);
layerFilter->addLayer(layer1);

...

另请参阅 Qt3DRender::QLayerFilter 。

[deprecated] class Qt3DRender::QLayerFilter

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QLayerFilter 可用于指示渲染器在帧图的该分支中绘制哪些图层。QLayerFilter 会根据添加到 QLayerFilter 以及作为Qt3DCore::QEntity 组件的QLayer 实例，来选择要绘制的实体。

QLayerFilter 可配置为根据filterMode 属性，选择或剔除具有特定QLayer 的实体。默认情况下，引用了QLayer 对象之一且该对象同时被QLayerFilter 引用的实体将被选中（AcceptAnyMatchingLayers ）。

在 FrameGraph 树中，从根节点到叶节点的分支内可以嵌套多个QLayerFilter 节点。 在这种情况下，过滤操作将首先针对场景中的所有实体，使用第一个声明的QLayerFilter 所指定的过滤方法进行处理。然后，对经过过滤的实体子集再次进行过滤，基于第二个声明的QLayerFilter 上设置的过滤方法。此过程将重复进行，直到该分支中的所有QLayerFilter 节点均被处理完毕。

[deprecated] class Qt3DRender::QLevelOfDetail

该类已弃用。我们强烈建议不要在新的代码中使用它。

QLevelOfDetail 可用于根据实体与观察者之间的距离或其在屏幕上的大小来控制实体的呈现效果。

为了提高渲染性能，非常小的对象在几何体或纹理渲染时可以使用更少的细节。

该组件通过指定阈值来控制，这些阈值会被解释为距离摄像机的距离或屏幕尺寸。

随着视角的变化，currentIndex 属性也会随之变化，以反映范围数组中的对应值。

然后，可以使用“currentIndex ”属性来启用或禁用实体、更改材质等。

LevelOfDetail 组件无法在多个entities 之间共享。

 #include <Qt3DCore/QEntity>
 #include <Qt3DRender/QGeometryRenderer>
 #include <Qt3DRender/QLevelOfDetail>

// Scene
Qt3DCore::QEntity *rootEntity = new Qt3DCore::Qt3DCore::QEntity;

Qt3DCore::QEntity *renderableEntity = new Qt3DCore::QEntity(rootEntity);
Qt3DRender::QGeometryRenderer *geometryRenderer = new Qt3DCore::QGeometryRenderer(renderableEntity);
renderableEntity->addComponent(geometryRenderer);
Qt3DRender::QLevelOfDetail* lod = new Qt3Render::QLevelOfDetail(renderableEntity);
QList<qreal> thresholds = {20, 35, 50, 65};
lod->setThresholds(thresholds);
lod->setCamera(mainCamera);
renderableEntity->addComponent(lod);

// connect to QLevelOfDetail::currentIndexChanged to toggle rendering
...

[deprecated] class Qt3DRender::QLevelOfDetailBoundingSphere

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QLevelOfDetailSwitch

该类已弃用。我们强烈建议不要在新代码中使用它。

该组件被分配给一个实体。当该实体相对于摄像机的距离发生变化时，QLevelOfDetailSwitch 将禁用所有子实体，但与索引 Qt3DRender::QLevelOfDetailSwitch::currentIndex 匹配的实体除外。

[deprecated] class Qt3DRender::QLineWidth

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QMaterial

该类已弃用。我们强烈建议不要在新代码中使用它。

QMaterial 提供了一种指定entity 渲染方式的方法。任何方面都可以定义自己的 QMaterial 子类，从而利用 Material 来描述视觉元素；例如，声音在元素上的反射方式、表面的温度等等。

QMaterial 本身并不执行任何操作。只有当它引用一个QEffect 节点时，QMaterial 才发挥作用。

实际上，经常会出现一个QEffect 被多个QMaterial组件引用的情况。这使得只需创建一次效果、技术、通道和着色器，同时可以通过添加QParameter 实例来指定材质。

在 QMaterial 上定义的QParameter 会覆盖QEffect 、QTechnique 和QRenderPass 中定义的（同名）参数，但会被QRenderPassFilter 和QTechniqueFilter 中的参数所覆盖。

QMaterial *material1 = new QMaterial();
QMaterial *material2 = new QMaterial();

// Create effect, technique, render pass and shader
QEffect *effect = new QEffect();
QTechnique *gl3Technique = new QTechnique();
QRenderPass *gl3Pass = new QRenderPass();
QShaderProgram *glShader = new QShaderProgram();

// Set the shader on the render pass
gl3Pass->setShaderProgram(glShader);

// Add the pass to the technique
gl3Technique->addRenderPass(gl3Pass);

// Set the targeted GL version for the technique
gl3Technique->graphicsApiFilter()->setApi(QGraphicsApiFilter::OpenGL);
gl3Technique->graphicsApiFilter()->setMajorVersion(3);
gl3Technique->graphicsApiFilter()->setMinorVersion(1);
gl3Technique->graphicsApiFilter()->setProfile(QGraphicsApiFilter::CoreProfile);

// Add the technique to the effect
effect->addTechnique(gl3Technique);

// Set the effect on the materials
material1->setEffect(effect);
material2->setEffect(effect);

// Set different parameters on the materials
const QString parameterName = QStringLiteral("color");
material1->addParameter(new QParameter(parameterName, QColor::fromRgbF(0.0f, 1.0f, 0.0f, 1.0f)));
material2->addParameter(new QParameter(parameterName, QColor::fromRgbF(1.0f, 1.0f, 1.0f, 1.0f)));

另请参阅 QEffect 、QTechnique 以及QParameter 。

[deprecated] class Qt3DRender::QMemoryBarrier

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QMemoryBarrier 的 FrameGraph 节点用于在渲染的特定时刻插入特定的内存屏障。这是在 GPU 上正确同步绘制和计算命令所必需的。

该屏障定义了先前命令发出的内存操作的执行顺序。这意味着，如果命令1正在操作一个将在后续命令2中用作顶点属性缓冲区的缓冲区，则应将内存屏障置于命令1之后，并为顶点属性缓冲区设置适当的屏障类型。

当在 FrameGraph 分支中发现 QMemoryBarrier 节点时，即使绘制或计算命令定义在分支更深处，该屏障也会在任何绘制或计算命令之前被强制执行。

关于 OpenGL 渲染，本页面提供了有关内存模型的更多信息

[deprecated] class Qt3DRender::QMesh

该类已弃用。我们强烈建议不要在新代码中使用它。

从多种格式的外部文件中加载网格数据。Qt3DRender::QMesh 将数据加载到单个网格中。

在 Qt3D 5.9 中，QMesh 支持以下格式：

• Wavefront OBJ
• 斯坦福三角格式 PLY
• STL（立体光刻）

如果已安装 SDK，并且已构建并找到 fbx 几何体加载器插件，QMesh 还将支持以下格式：

• Autodesk FBX

若需加载由多个对象组成的完整场景，建议改用Qt3DRender::QSceneLoader 。

另请参阅 Qt3DRender::QSceneLoader 。

[deprecated] class Qt3DRender::QMultiSampleAntiAliasing

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QMultiSampleAntiAliasing 类可启用多采样抗锯齿功能。

可通过调用 `QRenderPass::addRenderState()` 将其添加到 `QRenderPass ` 对象中：

QRenderPass *renderPass = new QRenderPass();

QMultiSampleAntiAliasing *msaa = new QMultiSampleAntiAliasing();
renderPass->addRenderState(msaa);

或者通过调用 `QRenderStateSet::addRenderState()` 向 `QRenderStateSet ` 添加该功能：

QRenderStateSet *renderStateSet = new QRenderStateSet();

QMultiSampleAntiAliasing *msaa = new QMultiSampleAntiAliasing();
renderStateSet->addRenderState(msaa);

要使多采样生效，渲染目标必须是在启用多采样的情况下分配的：

QTexture2DMultisample *colorTex = new QTexture2DMultisample;
colorTex->setFormat(QAbstractTexture::RGBA8_UNorm);
colorTex->setWidth(1024);
colorTex->setHeight(1024);

QRenderTargetOutput *color = new QRenderTargetOutput;
color->setAttachmentPoint(QRenderTargetOutput::Color0);
color->setTexture(colorTex);

QTexture2DMultisample *depthStencilTex = new QTexture2DMultisample;
depthStencilTex->setFormat(QAbstractTexture::RGBA8_UNorm);
depthStencilTex->setWidth(1024);
depthStencilTex->setHeight(1024);

QRenderTargetOutput *depthStencil = new QRenderTargetOutput;
depthStencil->setAttachmentPoint(QRenderTargetOutput::DepthStencil);
depthStencil->setTexture(depthStencilTex);

Qt3DRender::QRenderTarget *renderTarget = new Qt3DRender::QRenderTarget;
renderTarget->addOutput(color);
renderTarget->addOutput(depthStencil);

此外，着色器代码必须使用多采样采样器类型，并使用 `texelFetch()` 代替 `texture()`。

例如，如果您有如下代码：

#version 150

uniform sampler2D colorTexture;
in vec2 texCoord;
out vec4 fragColor;

void main()
{
    fragColor = texture(colorTexture, texCoord);
}

则可将其重写为

#version 150

uniform sampler2DMS colorTexture;
in vec2 texCoord;
out vec4 fragColor;

void main()
{
    ivec2 tc = ivec2(floor(textureSize(colorTexture) * texCoord));
    vec4 c = texelFetch(colorTexture, tc, 0) +
                texelFetch(colorTexture, tc, 1) +
                texelFetch(colorTexture, tc, 2) +
                texelFetch(colorTexture, tc, 3);
    fragColor = c / 4.0;
}

[deprecated] class Qt3DRender::QNoDepthMask

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QNoDepthMask 类会禁用将片段深度写入深度缓冲区。

另请参阅 Qt3DRender::QDepthTest 。

[deprecated] class Qt3DRender::QNoDraw

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QNoDraw 当 FrameGraph 需要设置某些渲染状态或清除某些缓冲区，但又无需绘制任何网格时，应使用该类。其效果等同于拥有一个与场景中所有可用Qt3DRender::QRenderPass 实例均不匹配的Qt3DRender::QRenderPassFilter ，同时避免了实际执行过滤操作带来的开销。

当禁用时，Qt3DRender::QNoDraw 节点不会阻止场景的渲染。因此，切换enabled属性是使Qt3DRender::QNoDraw 激活或停用的方法。

Qt3DRender::QNoDraw 该节点通常作为 Qt3DRendeR::QClearBuffers 节点的子节点使用，以防止在存在多个渲染通道时渲染场景。

Qt3DRender::QViewport *viewport = new Qt3DRender::QViewport();
Qt3DRender::QCameraSelector *cameraSelector = new Qt3DRender::QCameraSelector(viewport);

Qt3DRender::QClearBuffers *clearBuffers = new Qt3DRender::QClearBuffers(cameraSelector);
clearBuffers->setBuffers(Qt3DRender::QClearBuffers::ColorDepthBuffer);

Qt3DRender::QNoDraw *noDraw = new Qt3DRender::QNoDraw(clearBuffers);

Qt3DRender::QRenderPassFilter *mainPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
....
Qt3DRender::QRenderPassFilter *previewPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
....

[deprecated] class Qt3DRender::QNoPicking

该类已弃用。我们强烈建议不要在新代码中使用它。

当禁用时，Qt3DRender::QNoPicking 节点不会阻止拾取操作的执行。因此，切换enabled属性的状态是使Qt3DRender::QNoPicking 节点处于活动或非活动状态的一种方式。

在 FrameGraph 中使用多个子视口时，QNoPicking 可用于防止重叠视口或非可见视口之间的选取冲突。它还可以作为一种优化手段，避免为隐藏视口或场景中无需进行选取的区域执行不必要的工作。

Qt3DRender::QViewport *viewport = new Qt3DRender::QViewport();
Qt3DRender::QCameraSelector *cameraSelector = new Qt3DRender::QCameraSelector(viewport);
Qt3DRender::QNoPicking *noPicking = new Qt3DRender::QNoPicking(cameraSelector);

Qt3DRender::QClearBuffers *clearBuffers = new Qt3DRender::QClearBuffers(noPicking);
clearBuffers->setBuffers(Qt3DRender::QClearBuffers::ColorDepthBuffer);

Qt3DRender::QRenderPassFilter *mainPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
....
Qt3DRender::QRenderPassFilter *previewPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
....

另请参阅 Qt3DRender::QObjectPicker 、Qt3DRender::QRayCaster 以及Qt3DRender::QScreenRayCaster 。

[deprecated] class Qt3DRender::QObjectPicker

该类已弃用。我们强烈建议不要在新代码中使用它。

对于每种视口和摄像机的组合，“拾取”操作会向场景中投射一条光线，以查找其包围体与该光线相交的实体。包围体是通过几何体中 `boundingVolumePositionAttribute` 属性指定的属性缓冲区中的值计算得出的。

当由 `pickAttribute` 属性定义的包围体与光线发生相交时，将触发以下信号：pressed()、released()、clicked()、moved()、entered() 以及exited()。

大多数信号都携带一个 `QPickEvent ` 实例。如果 `QPickingSettings::pickMode()` 设置为 `QPickingSettings::TrianglePicking`，则 `pick` 参数的实际类型将为 `QPickTriangleEvent`。

拾取查询在鼠标按下和松开时执行。如果启用了拖动功能，则在按住任何按钮时，每次鼠标移动都会触发查询。如果启用了悬停功能，即使未按下任何按钮，每次鼠标移动也会触发查询。

有关通用的射线投射查询，请参阅Qt3DRender::QRayCaster 和Qt3DRender::QScreenRayCaster 。

另请参阅 Qt3DRender::QPickingSettings 、Qt3DCore::QGeometry 、Qt3DCore::QAttribute 、Qt3DRender::QPickEvent 、Qt3DRender::QPickTriangleEvent 以及Qt3DRender::QNoPicking 。

[deprecated] class Qt3DRender::QPaintedTextureImage

该类已弃用。我们强烈建议不要在新代码中使用它。

QPaintedTextureImage 提供了一种通过 `QPainter` 指定纹理图像（即 OpenGL 纹理）的方法。纹理图像的宽度和高度可通过 `width`、`height` 或 `size` 属性进行指定。

必须对 QPaintedTextureImage 进行子类化，并实现虚拟函数paint()。每次在 QPaintedTextureImage 上调用update() 时，都会调用paint() 函数，并将生成的图像上传。

QPaintedTextureImage 必须与某个QAbstractTexture 相关联。

[deprecated] class Qt3DRender::QParameter

该类已弃用。我们强烈建议不要在新的代码中使用它。

可以通过以下方式引用 QParameter：QRenderPass 、QTechnique 、QEffect 、QMaterial 、QTechniqueFilter 、QRenderPassFilter 。在运行时，根据渲染的特定步骤所选定的着色器，如果该着色器中包含一个名称与 QParameter 匹配的 uniform，则 QParameter 中包含的值将被转换并上传。

QParameter *param = new QParameter();
param->setName(QStringLiteral("diffuseColor"));
param->setValue(QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));

// Alternatively you can create and set a QParameter this way
QParameter *param2 = new QParameter(QStringLiteral("diffuseColor"), QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));

// Such QParameters will work with the following GLSL uniform shader declarations
// uniform vec4 diffuseColor;
// uniform vec3 diffuseColor;
// uniform vec2 diffuseColor;
// uniform float diffuseColor;

QParameter *param = new QParameter();
QVariantList values = QVariantList() << 0.0f << 1.0f << 2.0f << 3.0f << 4.0f << 883.0f << 1340.0f << 1584.0f;

param->setName(QStringLiteral("diffuseValues[0]"));
param->setValue(values);

// Matching GLSL shader uniform  declaration
// uniform float diffuseValues[8];

在纹理支持方面，QParameter 的值应设置为与着色器统一变量的采样器类型相匹配的适当QAbstractTexture 子类。

QTexture2D *texture = new QTexture2D();
...
QParameter *param = new QParameter();
param->setName(QStringLiteral("diffuseTexture"));
param->setValue(QVariant::fromValue(texture));

// Works with the following GLSL uniform shader declaration
// uniform sampler2D diffuseTexture

另请参阅 QAbstractTexture 。

[deprecated] class Qt3DRender::QPickEvent

该类已弃用。我们强烈建议不要在新代码中使用它。

在QObjectPicker 组件的大多数信号中，当选择操作成功时，该参数会被作为参数接收。

另请参阅 QPickingSettings 、QPickTriangleEvent 和QObjectPicker 。

[deprecated] class Qt3DRender::QPickLineEvent

该类已弃用。我们强烈建议不要在新代码中使用它。

另请参阅 QPickEvent 。

[deprecated] class Qt3DRender::QPickPointEvent

该类已被废弃。我们强烈建议不要在新代码中使用它。

另请参阅 QPickEvent 。

[deprecated] class Qt3DRender::QPickTriangleEvent

该类已弃用。我们强烈建议不要在新代码中使用它。

当 QPickingSettings::pickMode() 设置为QPickingSettings::TrianglePicking 时，QObjectPicker 上的信号将传递一个 QPickTriangleEvent 实例。

该对象包含所选三角形的详细信息。

另请参阅 QPickingSettings 、QPickEvent 和QObjectPicker 。

[since 6.0, deprecated] class Qt3DRender::QPickingProxy

该类已弃用。我们强烈建议不要在新代码中使用它。

选择操作可能消耗大量资源，尤其是当网格包含大量顶点时。可以使用 QPickProxy 提供一种替代几何体（通常包含较少的基元），该几何体将用于选择操作，而GeometryRenderer 实例则用于渲染。

该类在 Qt 6.0 中引入。

[deprecated] class Qt3DRender::QPickingSettings

该类已弃用。我们强烈建议不要在新代码中使用它。

选择设置决定了如何处理实体选择。有关实体选择的更多详细信息，请参阅QObjectPicker 和QRayCaster 组件文档。

使用QObjectPicker 组件时，选择操作由鼠标事件触发。

使用QRayCaster 或QScreenRayCaster 组件时，应用程序可以显式触发选择操作。

在这两种情况下，系统都会向场景中投射一条光线，以查找与该光线相交的几何体。

另请参阅 QObjectPicker 、QPickEvent 、QPickTriangleEvent 、QRayCaster 以及QScreenRayCaster 。

[deprecated] class Qt3DRender::QPointLight

该类已弃用。我们强烈建议不要在新代码中使用它。

点光源是一种从单一点向各个方向发射光线的光源。从概念上讲，这类似于普通灯泡发出的光。

点光源使用三个衰减因子来描述光强度随距离的衰减情况。这些因子旨在共同用于计算总衰减量。对于 Qt3D Extras 中的材质，采用以下公式，其中距离是指光源到待渲染表面的距离：

totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));

自定义材质可能会对这些系数进行不同的解释。

[deprecated] class Qt3DRender::QPointSize

该类已弃用。我们强烈建议不要在新代码中使用它。

当sizeMode 属性设置为SizeMode::Fixed 时，如果可用，将通过glPointSize()设置该值。当使用SizeMode::Programmable 时，必须在着色器程序中设置gl_PointSize；在此情况下，提供给此RenderState 的值将被忽略。

[deprecated] class Qt3DRender::QPolygonOffset

该类已弃用。我们强烈建议不要在新代码中使用它。

QPolygonOffset 类会在深度测试和深度写入之前，对片段深度值添加一个偏移量。当渲染深度值非常接近的多边形（例如贴花）时，该偏移量可用于避免 Z 冲突。

[deprecated] class Qt3DRender::QProximityFilter

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QProximityFilter 可用于选择位于另一个实体指定距离阈值范围内的实体进行渲染。

[deprecated] class Qt3DRender::QRasterMode

该类已弃用。我们强烈建议不要在新代码中使用它。

QRasterMode 类用于在渲染时控制基元的光栅化步骤。可通过它来选择仅显示点、边，还是填充基元。

另请参阅 QAlphaTest 和QStencilTest 。

[deprecated] class Qt3DRender::QRayCaster

该类已弃用。我们强烈建议不要在新的代码中使用它。

3D射线由其起点、方向和长度定义。它将受到所属实体所应用的变换的影响。

只要该组件处于启用状态，每帧都会执行射线投射测试。`hits` 属性将更新为交点列表。

另请参阅 QAbstractRayCaster 、QScreenRayCaster 以及QNoPicking 。

[deprecated] class Qt3DRender::QRayCasterHit

该类已弃用。我们强烈建议不要在新的代码中使用它。

Qt3DRender::QRayCasterHit 包含使用Qt3DRender::QRayCaster 或Qt3DRender::QScreenRayCaster 组件通过模型投射光线时，成功命中事件的详细信息。

另请参阅 Qt3DRender::QRayCaster 、Qt3DRender::QScreenRayCaster 和Qt3DRender::QPickingSettings 。

[deprecated] class Qt3DRender::QRenderAspect

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QRenderCapabilities

该类已弃用。我们强烈建议不要在新代码中使用它。

QRenderCapabilities 提供了运行时可用图形功能的详细信息。它可用于决定某些算法应采用哪条代码路径，例如，根据计算着色器是否可用来决定。

[deprecated] class Qt3DRender::QRenderCapture

该类已弃用。我们强烈建议不要在新代码中使用它。

QRenderCapture 用于在任何渲染阶段将渲染结果捕获到图像中。捕获操作必须由用户发起，每次捕获请求会返回一张图像。用户可以同时发出多个渲染捕获请求，但每个帧内，每个 QRenderCapture 实例仅处理一个请求。

[deprecated] class Qt3DRender::QRenderCaptureReply

该类已弃用。我们强烈建议不要在新代码中使用它。

一个从QRenderCapture::requestCapture 接收图像的对象。

[deprecated] class Qt3DRender::QRenderPass

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QRenderPass 指定了一个渲染通道（即着色器程序执行的单次实例），供Qt3DRender::QTechnique 使用。渲染通道由一个Qt3DRender::QShaderProgram 、一组Qt3DRender::QFilterKey 对象、一组Qt3DRender::QRenderState 对象以及一组Qt3DRender::QParameter 对象组成。

当被引用的QFilterKey 节点中至少有一个与QRenderPassFilter 中的QFilterKey 节点匹配时，或者未指定任何QFilterKey 节点且FrameGraph中不存在QRenderPassFilter 时，QRenderPass将使用给定的QRenderState 和QParameter 节点来执行QShaderProgram 。

如果 QRenderPass 定义了QParameter ，当运行时与该渲染通道关联的QTechnique 、QEffect 、QMaterial 、QTechniqueFilter 或QRenderPassFilter 中存在同名的QParameter 时，该默认渲染状态将被后者覆盖。这对于定义合理的默认值仍然很有用。

在渲染时，对于FrameGraph中的每个叶节点，会通过累加FrameGraph分支中所有QRenderStateSet 节点定义的状态来记录一个基础渲染状态。每个QRenderPass都可以通过指定自己的QRenderState 节点来覆盖此基础渲染状态。

// Create the render passes
QRenderPass *pass = new QRenderPass();

// Create shader program
QShaderProgram *glShader = new QShaderProgram();

// Set the shader on the render pass
pass->setShaderProgram(glShader);

// Create a FilterKey
QFilterKey *filterKey = new QFilterKey();
filterKey->setName(QStringLiteral("name"));
fitlerKey->setValue(QStringLiteral("zFillPass"));

// Add the FilterKey to the pass
pass->addFilterKey(filterKey);

// Create a QParameter
QParameter *colorParameter = new QParameter(QStringLiteral("color"), QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));

// Add parameter to pass
pass->addParameter(colorParameter);

// Create a QRenderState
QDepthTest *depthTest = new QDepthTest();

// Add the render state to the pass
pass->addRenderState(depthTest);

另请参阅 QRenderPassFilter 、QFilterKey 、QParameter 、QRenderState 、QEffect 以及QTechnique 。

[deprecated] class Qt3DRender::QRenderPassFilter

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QRenderPassFilter 的FrameGraph节点用于选择哪些Qt3DRender::QRenderPass 对象将被选中进行渲染。QRenderPassFilter指定了一组Qt3DRender::QFilterKey 对象和Qt3DRender::QParameter 对象的列表。当FrameGraph中存在QRenderPassFilter时，只有那些其Qt3DRender::QFilterKey 对象与QRenderPassFilter中的键值匹配的QRenderPass 对象会被选中进行渲染。 如果不存在 QRenderPassFilter，则所有QRenderPass 对象都会被选中进行渲染。列表中的参数可用于设置着色器参数的值。QRenderPassFilter 中的参数会覆盖QTechniqueFilter 、QMaterial 、QEffect 、QTechnique 和QRenderPass 中的参数。

[deprecated] class Qt3DRender::QRenderSettings

该类已弃用。我们强烈建议不要在新代码中使用它。

QRenderSettings 组件必须设置为场景根实体的组件。它指定渲染策略和拾取设置，并托管活动的FrameGraph。

[deprecated] class Qt3DRender::QRenderState

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QRenderState 类是所有渲染状态的抽象基类。无法直接实例化 QRenderState，而必须通过其子类进行实例化。

[deprecated] class Qt3DRender::QRenderStateSet

该类已弃用。我们强烈建议不要在新代码中使用它。

与可在QRenderPass 上设置的“按材质”状态不同，在QRenderStateSet上设置的状态是全局生效的。默认情况下，空的QRenderStateSet在执行时会导致所有渲染状态被禁用。显式添加QRenderState 状态会在运行时启用该渲染状态。

将RenderStateSet 添加到活动帧图中时，该材质状态即被启用：

// using namespace Qt3DRender;

Qt3DCore::QEntity *rootEntity = new Qt3DCore::QEntity();

QRenderSettings *renderSettings = new QRenderSettings();

QViewport *viewport = new QViewport();
QCameraSelector *cameraSelector = new QCameraSelector(viewport);

QClearBuffers *clearBuffers = new QClearBuffers(cameraSelector);
clearBuffers->setBuffers(QClearBuffers::ColorDepthBuffer);

QRenderStateSet *renderStateSet = new QRenderStateSet(cameraSelector);
QCullFace *cullFace = new QCullFace(renderStateSet);
cullFace->setMode(QCullFace::Front);
renderStateSet->addRenderState(cullFace);

renderSettings->setActiveFrameGraph(viewport);

rootEntity->addComponent(renderSettings);

另请参阅 QRenderState 和QRenderPass 。

[deprecated] class Qt3DRender::QRenderSurfaceSelector

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QRenderSurfaceSelector 用于选择 Qt3D 渲染内容的渲染面。该渲染面可以是窗口渲染面，也可以是离屏渲染面。当使用离屏渲染面时，externalRenderTargetSize 用于指定渲染面的实际尺寸。

当系统启用 DPI 缩放时，用于处理鼠标事件的逻辑表面尺寸与表面的实际“物理”尺寸可能会存在差异。surfacePixelRatio 是将逻辑尺寸转换为物理尺寸的转换因子。

另请参阅 QWindow 、QOffscreenSurface 和QSurface 。

[deprecated] class Qt3DRender::QRenderTarget

该类已弃用。我们强烈建议不要在新代码中使用它。

一个渲染目标（Qt3DRender::QRenderTarget ）由多个渲染目标缓冲区（Qt3DRender::QRenderTargetOutput ）对象组成，这些对象指定了渲染目标的渲染目标。用户可以通过将多个纹理附加到不同的附加点来指定 MRT（多渲染目标）。如果用户尝试将多个纹理附加到同一个附加点，则结果未定义。 在渲染时，仅使用Qt3DRender::QRenderTargetSelector 中指定的绘制缓冲区。

[deprecated] class Qt3DRender::QRenderTargetOutput

该类已弃用。我们强烈建议不要在新代码中使用它。

QRenderTargetOutput 用于指定附着于渲染目标的纹理的附着点和参数。除了附着点之外，还可以指定纹理的 Mip 级别、图层和立方贴图面。附着于 QRenderTargetOutput 的纹理必须与给定的参数兼容。

[deprecated] class Qt3DRender::QRenderTargetSelector

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QRenderTargetSelector 用于为 FrameGraph 选择活动的Qt3DRender::QRenderTarget 。当 FrameGraph 中存在 QRenderTargetSelector 时，渲染结果将被导向 QTexture 对象或绘制缓冲区，而不是Qt3DRender::QRenderSurfaceSelector 中指定的表面。

[deprecated] class Qt3DRender::QSceneLoader

该类已弃用。我们强烈建议不要在新代码中使用它。

给定一个 3D 源文件，Qt3DRender::QSceneLoader 将尝试解析该文件，并构建一个由Qt3DCore::QEntity 对象组成的树，其中包含相应的Qt3DRender::QGeometryRenderer 、Qt3DCore::QTransform 和Qt3DRender::QMaterial 组件。

加载器将根据模型文件的属性尝试确定最佳材质。若您希望使用自定义材质，则需遍历该树，并将默认关联的材质替换为您自己的材质。

顾名思义，Qt3DRender::QSceneLoader 用于加载完整的场景子树。如果您只想加载单个几何体，则应改用Qt3DRender::QMesh 。

Qt3DRender::QSceneLoader 在内部，xml-ph-0000@deepl.internal 依赖于插件来支持多种 3D 文件格式。以下是Qt3D 支持的格式列表。

另请参阅 Qt3DRender::QMesh 和Qt3DRender::QGeometryRenderer 。

[deprecated] class Qt3DRender::QScissorTest

该类已弃用。我们强烈建议不要在新代码中使用它。

QScissorTest 类可启用剪刀测试功能，该功能会舍弃位于屏幕中由 left、bottom、width 和 height 属性指定的矩形区域之外的片段。

[deprecated] class Qt3DRender::QScreenRayCaster

该类已弃用。我们强烈建议不要在新代码中使用它。

QScreenRayCaster 可通过指定屏幕空间中的坐标来执行光线投射测试，这些坐标将用于在近平面和远平面之间构建实际的 3D 光线。

另请参阅 QRayCaster 和QNoPicking 。

[deprecated] class Qt3DRender::QSeamlessCubemap

该类已弃用。我们强烈建议不要在新代码中使用它。

当该类出现在状态集中时，将启用由 GL_ARB_seamless_cubemap 扩展（若可用）提供的无缝立方贴图纹理过滤功能。

[deprecated] class Qt3DRender::QSetFence

该类已弃用。我们强烈建议在新代码中不要使用它。

Fence 允许同步 GPU 和 CPU 的工作负载。GPU 命令通常是非阻塞的。当发出命令时，这些命令会被插入到命令缓冲区中，随后由 GPU 读取。在某些情况下，您可能希望仅在确信某个命令已被硬件执行后，才继续处理或发出特定命令。 栅栏（Fence）正是实现这一目标的手段。这在使用第三方引擎与 Qt3D 配合时尤为重要，Qt3D 仅应在确定其他引擎的命令已完成对资源的修改后，才访问共享资源。

QSetFence 是一个 FrameGraph 节点，用于将栅栏插入命令流中。随后，它可与 `QWaitFence ` 配合使用，或通过提取底层句柄来使用。

一旦渲染器创建了底层栅栏资源，handle 属性就会被更新。 只要该句号处于未触发状态，句号就保持有效。一旦进入触发状态，它将被销毁并生成一个新的句号。这意味着，根据句号被触发的耗时长短，同一个句号可能在多个帧中被重复使用。

[deprecated] class Qt3DRender::QShaderData

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QShaderImage

该类已弃用。我们强烈建议不要在新代码中使用它。

为了使着色器中能够对纹理内容进行读写操作，需要将其作为 QShaderImage 进行暴露。纹理可以由多个 Mip 级别、图层和面组成。此外，声明一个 QShaderImage 还可以指定我们要访问的纹理内容的具体级别、图层或面。

QShaderImage必须被赋值为QParameter 的值，并引用一个有效的Qt3DRender::QAbstractTexture ，才能正常工作。

如果引用的纹理是一维数组、二维数组、三维数组、立方体贴图、立方体贴图数组或二维多采样数组纹理，则可以绑定整个纹理级别，也可以绑定该级别中的单个层或面。这可以通过layered 属性进行控制。

QShaderImage 仅在 OpenGL 4 中受支持，在 OpenGL ES 3.1 和 3.2 中仅部分受支持。

OpenGL 4 支持以下图像类型：

OpenGL ES 3.1 支持以下图像类型：

OpenGL ES 3.2 支持所有 OpenGL ES 3.1 图像类型，以及以下类型：

预期用法如下：

Qt3DRender::QTexture2D *tex2D = new Qt3DRender::QTexture2D();
...
Qt3DRender::QMaterial *material = new Qt3DRender::QMaterial();
...
Qt3DRender::QParameter *imageParameter = new Qt3DRender::QParameter();
Qt3DRender::QShaderImage *shaderImage = new Qt3DRender::QShaderImage();

shaderImage->setTexture(tex2D);

imageParameter->setName("imageUniformName");
imageParameter->setValue(QVariant::fromValue(shaderImage));

material->addParameter(imageParamenter);

[deprecated] class Qt3DRender::QShaderProgram

该类已弃用。我们强烈建议不要在新的代码中使用它。

一个着色器程序由多个不同的着色器组成，例如顶点着色器和片段着色器。

如果在着色器内省阶段遇到这些着色器，Qt3D 将自动填充一组默认统一变量。

RHI 支持

在编写用于Qt 3D 的RHI后端的GLSL 450着色器代码时，默认的uniform变量将作为2个uniform缓冲区对象提供。

这些变量的绑定位置设置为：RenderView 统一变量绑定到 0，Command 统一变量绑定到 1。

#version 450 core

layout(location = 0) in vec3 vertexPosition;

layout(std140, binding = 0) uniform qt3d_render_view_uniforms {
  mat4 viewMatrix;
  mat4 projectionMatrix;
  mat4 uncorrectedProjectionMatrix;
  mat4 clipCorrectionMatrix;
  mat4 viewProjectionMatrix;
  mat4 inverseViewMatrix;
  mat4 inverseProjectionMatrix;
  mat4 inverseViewProjectionMatrix;
  mat4 viewportMatrix;
  mat4 inverseViewportMatrix;
  vec4 textureTransformMatrix;
  vec3 eyePosition;
  float aspectRatio;
  float gamma;
  float exposure;
  float time;
  float yUpInNDC;
  float yUpInFBO;
};

layout(std140, binding = 1) uniform qt3d_command_uniforms {
  mat4 modelMatrix;
  mat4 inverseModelMatrix;
  mat4 modelViewMatrix;
  mat3 modelNormalMatrix;
  mat4 inverseModelViewMatrix;
  mat4 modelViewProjection;
  mat4 inverseModelViewProjectionMatrix;
};

void main()
{
    gl_Position = (projectionMatrix * viewMatrix * modelMatrix * vertexPosition);
}

对于用户定义的uniform缓冲区对象，请使用从2开始的绑定，或使用auto让Qt 3D 自动处理绑定。请确保在不同的着色器阶段之间保持一致。

#version 450 core

layout(std140, binding = auto) uniform my_uniforms {
  vec4 myColor;
};

layout(location=0) out vec4 fragColor;

void main()
{
    fragColor = myColor;
}

向统一变量赋值时无需进行任何更改。

对于上述示例，可以这样设置 myColor：

QParameter *parameter = new QParameter();
parameter->setName("myColor");
parameter->setValue(QVariant::fromValue(QColor(Qt::blue)));

纹理仍需定义为独立的uniform。

#version 450 core

layout(binding=0) uniform sampler2D source;

layout(location=0) out vec4 fragColor;

void main()
{
    fragColor = texture(source, vec2(0.5, 0.5));
}

[deprecated] class Qt3DRender::QShaderProgramBuilder

该类已弃用。我们强烈建议不要在新代码中使用它。

着色器程序生成器由多个不同的着色器图组成，用于生成着色器代码。

系统会维护一个生成的着色器代码缓存。生成的着色器默认保存在QStandardPaths::writableLocation （QStandardPaths::TempLocation ）中。可以通过将环境变量 QT3D_WRITABLE_CACHE_PATH 设置为有效的可写路径来覆盖此路径。

可以通过将环境变量 QT3D_DISABLE_SHADER_CACHE 设置为相应值来禁用缓存。

在大多数情况下，对图形所做的更改会被Qt 3D 检测到，并生成新的缓存条目。 唯一不会发生这种情况的情况是，当图中包含的代码片段发生更改时。要解决此问题，可以清空缓存目录或设置环境变量 QT3D_REBUILD_SHADER_CACHE，以强制重新生成着色器代码。

[deprecated] class Qt3DRender::QSharedGLTexture

该类已弃用。我们强烈建议不要在新代码中使用它。

根据Qt 3D 所使用的渲染模式，共享上下文将分别是：

• 当由 `Qt 3D ` 驱动渲染时，共享上下文为 `qt_gl_global_share_context`。若在 `QApplication` 类上设置 `Qt::AA_ShareOpenGLContexts ` 属性，这将自动使 `QOpenGLWidget` 实例的上下文与 `qt_gl_global_share_context` 共享。
• 来自QtQuick 场景的共享上下文。不过，您可能需要继承QWindow 类或使用 QtQuickRenderControl 来控制该共享上下文的具体值，尽管截至 5.13 版本，其默认值为 qt_gl_global_share_context。

任何与Qt 3D 渲染器共享上下文的第三方引擎，现在均可提供纹理 ID，这些 ID 将被Qt 3D 纹理引用。

您可以省略纹理属性的指定，Qt 3D 会在运行时尝试确定这些属性。如果您已知这些属性，当然也可以直接提供，从而避免Qt 3D 进行额外的工作。

请注意，如果您使用的是自定义材质和着色器，则需要指定要使用的正确采样器类型。

[deprecated] class Qt3DRender::QSortPolicy

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QSortPolicy 类用于存储FrameGraph所使用的排序类型。排序类型决定了可绘制实体在绘制前如何进行排序，从而确定绘制顺序。当FrameGraph中存在QSortPolicy时，排序机制由sortTypes 列表决定。 可以同时使用多种排序类型。如果 FrameGraph 中不存在 QSortPolicy，则实体将按照其在实体层次结构中的出现顺序进行绘制。

[deprecated] class Qt3DRender::QSpotLight

该类已弃用。我们强烈建议不要在新代码中使用它。

聚光灯是一种向特定方向发射锥形光束的光源。

聚光灯使用三个衰减因子来描述光强度随距离的衰减情况。这些因子旨在共同用于计算总衰减量。对于 Qt3D Extras 中的材质，采用以下公式，其中距离是指光源到被渲染表面的距离：

totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));

自定义材质可能会采用不同的方式解释这些因子。

[deprecated] class Qt3DRender::QStencilMask

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QStencilMask 类用于指定在模板测试后对模板值进行的写入掩码。可分别针对朝向前和朝向后的多边形指定不同的掩码。片元模板值在写入模板缓冲区之前，会与该掩码进行按“与”运算。

另请参阅 Qt3DRender::QStencilTest 。

[deprecated] class Qt3DRender::QStencilOperation

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QStencilOperation 类用于指定面向前和面向后的多边形的模板操作。模板操作控制着当模板测试和深度测试通过或失败时，对片元执行的操作。

另请参阅 Qt3DRender::QStencilTest 。

[deprecated] class Qt3DRender::QStencilOperationArguments

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QStencilOperationArguments 类用于指定模板运算的参数。

另请参阅 Qt3DRender::QStencilOperation 。

[deprecated] class Qt3DRender::QStencilTest

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QStencilTest 类用于指定模板测试的参数。模板测试包含三个参数：模板测试函数、模板测试掩码和模板参考值。QStencilTest允许分别针对朝向前侧和朝向后侧的多边形设置这些参数。

另请参阅 Qt3DRender::QStencilMask 和Qt3DRender::QStencilOperation 。

[deprecated] class Qt3DRender::QStencilTestArguments

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QStencilTestArguments 类用于指定模板测试的参数。

[deprecated] class Qt3DRender::QSubtreeEnabler

该类已弃用。我们强烈建议不要在新代码中使用它。

虽然可以通过enabled 属性单独启用或禁用QFrameGraphNodes，但当需要启用或禁用整个路径时，这种操作会变得十分繁琐。QSubtreeEnabler是一个便捷节点，它使这种用例变得轻而易举，允许通过一个开关控制其所有子节点。

QSubtreeEnabler 默认处于启用状态。

[deprecated] class Qt3DRender::QTechnique

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QTechnique 指定了一组Qt3DRender::QRenderPass 对象、Qt3DRender::QFilterKey 对象、Qt3DRender::QParameter 对象以及一个Qt3DRender::QGraphicsApiFilter ，它们共同定义了给定图形 API 能够渲染的渲染技术。Qt3DRender::QTechniqueFilter 使用过滤器键在 FrameGraph 的特定部分选择特定的技术。在 QTechnique 上定义的QParameter 将覆盖在QRenderPass 中定义的（同名）参数，但会被QRenderPassFilter 、QTechniqueFilter 、QMaterial 和QEffect 中的参数所覆盖。

在创建针对多个图形 API 版本的QEffect 时，建议创建多个 QTechnique 节点，并将每个节点的graphicsApiFilter 设置为与目标 GL 版本之一相匹配。 在运行时，Qt3D 渲染器将根据支持的图形 API 版本，以及（如果已指定）在 FrameGraph 中满足给定QTechniqueFilter 的QFilterKey 节点，选择最合适的 QTechnique。

QTechnique *gl3Technique = new QTechnique();

// Create the render passes
QRenderPass *firstPass = new QRenderPass();
QRenderPass *secondPass = new QRenderPass();

// Add the passes to the technique
gl3Technique->addRenderPass(firstPass);
gl3Technique->addRenderPass(secondPass);

// Set the targeted GL version for the technique
gl3Technique->graphicsApiFilter()->setApi(QGraphicsApiFilter::OpenGL);
gl3Technique->graphicsApiFilter()->setMajorVersion(3);
gl3Technique->graphicsApiFilter()->setMinorVersion(1);
gl3Technique->graphicsApiFilter()->setProfile(QGraphicsApiFilter::CoreProfile);

// Create a FilterKey
QFilterKey *filterKey = new QFilterKey();
filterKey->setName(QStringLiteral("name"));
fitlerKey->setValue(QStringLiteral("zFillPass"));

// Add the FilterKey to the Technique
gl3Technique->addFilterKey(filterKey);

// Create a QParameter
QParameter *colorParameter = new QParameter(QStringLiteral("color"), QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));

// Add parameter to technique
gl3Technique->addParameter(colorParameter);

另请参阅 QEffect 、QRenderPass 以及QTechniqueFilter 。

[deprecated] class Qt3DRender::QTechniqueFilter

该类已弃用。我们强烈建议不要在新代码中使用它。

Qt3DRender::QTechniqueFilter 用于指定FrameGraph在渲染实体时所使用的技术。QTechniqueFilter指定了一组Qt3DRender::QFilterKey 对象和Qt3DRender::QParameter 对象的列表。当FrameGraph中存在QTechniqueFilter时，仅会使用与列表中键值匹配的技术进行渲染。 列表中的参数可用于设置着色器参数的值。QTechniqueFilter中的参数会覆盖QMaterial 、QEffect 、QTechnique 和QRenderPass 中的参数，但会被QRenderPassFilter 中的参数所覆盖。

[deprecated] class Qt3DRender::QTexture1D

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTexture1DArray

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTexture2D

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTexture2DArray

该类已弃用。我们强烈建议不要在新的代码中使用它。

[deprecated] class Qt3DRender::QTexture2DMultisample

该类已弃用。我们强烈建议不要在新的代码中使用它。

[deprecated] class Qt3DRender::QTexture2DMultisampleArray

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTexture3D

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureBuffer

该类已弃用。我们强烈建议不要在新的代码中使用它。

[deprecated] class Qt3DRender::QTextureCubeMap

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureCubeMapArray

该类已弃用。我们强烈建议不要在新的代码中使用它。

[deprecated] class Qt3DRender::QTextureData

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureDataUpdate

该类已弃用。我们强烈建议不要在新代码中使用它。

实际的数据内容包含在QTextureImageDataPtr 成员中。其他成员可用于指定内容更新的 x、y、z 偏移量，以及最终的图层、mipLevel 和面。

另请参阅 QAbstractTexture 。

[deprecated] class Qt3DRender::QTextureImage

该类已被弃用。我们强烈建议不要在新代码中使用它。

它包含将数据加载到 OpenGL 纹理正确位置所需的必要信息：Mipmap 级别、图层、立方体面和源 URL。

[deprecated] class Qt3DRender::QTextureImageData

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureImageDataGenerator

该类已弃用。我们强烈建议不要在新代码中使用它。

QTextureImageDataGenerator 是QAbstractTexture 的数据提供者。QTextureImageDataGenerator 可用于扩展 Qt3D，提供更多加载纹理图像数据的方式，并支持用户自定义格式以及 Qt3D 本身不原生支持的格式。 数据由QTextureImageDataPtr 返回，其中包含将加载到纹理中的数据。QTextureImageDataGenerator由后端的Aspect任务执行。

[deprecated] class Qt3DRender::QTextureLoader

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureRectangle

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QTextureWrapMode

该类已弃用。我们强烈建议不要在新代码中使用它。

[deprecated] class Qt3DRender::QViewport

该类已弃用。我们强烈建议不要在新的代码中使用它。

Qt3DRender::QViewport 场景的视口指定了 Qt3D 渲染到渲染表面的哪个区域。视口外的区域不会被渲染。它还控制着该视口内渲染的全局参数，例如伽马值。

[deprecated] class Qt3DRender::QWaitFence

该类已弃用。我们强烈建议不要在新代码中使用它。

Fence 用于同步 GPU 和 CPU 的工作负载。GPU 命令通常是非阻塞的。当发出命令时，这些命令会被插入到命令缓冲区中，随后由 GPU 读取。在某些情况下，您可能希望在确信某个命令已被硬件执行后，才继续处理或发出特定命令。 栅栏（Fence）正是实现这一目标的手段。当在 Qt3D 中使用第三方引擎时，这一点尤为重要——Qt3D 仅应在确知其他引擎的命令已完成对资源的修改后，才访问共享资源。

QWaitFence 是一个 FrameGraph 节点，它会强制等待该节点发出信号后，才允许后续命令插入到命令流中。它可以与QSetFence 配合使用，并包含用于配置等待时长以及是否在 CPU 端阻塞的属性。