Make old shadertools tests compile

...and some leftover docs

src/rhi/qrhi.cpp

@@ -320,12 +320,39 @@ QT_BEGIN_NAMESPACE
     \class QRhiViewport
     \inmodule QtRhi
     \brief Specifies a viewport rectangle.
+
+    Used with QRhiCommandBuffer::setViewport().
+
+    \note QRhi assumes OpenGL-style viewport coordinates, meaning x and y are
+    bottom-left.
+
+    Typical usage is like the following:
+
+    \badcode
+      const QSize outputSizeInPixels = swapchain->currentPixelSize();
+      const QRhiViewport viewport(0, 0, outputSizeInPixels.width(), outputSizeInPixels.height());
+      cb->beginPass(swapchain->currentFrameRenderTarget(), { 0, 0, 0, 1 }, { 1, 0 });
+      cb->setGraphicsPipeline(ps);
+      cb->setViewport(viewport);
+      ...
+    \endcode
+
+    \sa QRhiCommandBuffer::setViewport(), QRhi::clipSpaceCorrMatrix(), QRhiScissor
  */
 
 /*!
     \class QRhiScissor
     \inmodule QtRhi
     \brief Specifies a scissor rectangle.
+
+    Used with QRhiCommandBuffer::setScissor(). Setting a scissor rectangle is
+    only possible with a QRhiGraphicsPipeline that has
+    QRhiGraphicsPipeline::UsesScissor set.
+
+    \note QRhi assumes OpenGL-style viewport coordinates, meaning x and y are
+    bottom-left.
+
+    \sa QRhiCommandBuffer::setScissor(), QRhiViewport
  */
 
 /*!
@@ -338,6 +365,52 @@ QT_BEGIN_NAMESPACE
     \class QRhiVertexInputLayout::Binding
     \inmodule QtRhi
     \brief Describes a vertex input binding.
+
+    Specifies the stride (in bytes, must be a multiple of 4), the
+    classification and optionally the instance step rate.
+
+    As an example, assume a vertex shader with the following inputs:
+
+    \badcode
+        layout(location = 0) in vec4 position;
+        layout(location = 1) in vec2 texcoord;
+    \endcode
+
+    Now let's assume also that 3 component vertex positions \c{(x, y, z)} and 2
+    component texture coordinates \c{(u, v)} are provided in a non-interleaved
+    format in a buffer (or separate buffers even). Definining two bindings
+    could then be done like this:
+
+    \badcode
+        QRhiVertexInputLayout inputLayout;
+        inputLayout.bindings = {
+            { 3 * sizeof(float) },
+            { 2 * sizeof(float) }
+        };
+    \endcode
+
+    Only the stride is interesting here since instancing is not used. The
+    binding number is given by the index of the QRhiVertexInputLayout::Binding
+    element in the bindings vector of the QRhiVertexInputLayout.
+
+    Once a graphics pipeline with this vertex input layout is bound, the vertex
+    inputs could be set up like the following for drawing a cube with 36
+    vertices, assuming we have a single buffer with first the positions and
+    then the texture coordinates:
+
+    \badcode
+        cb->setVertexInput(0, { { cubeBuf, 0 }, { cubeBuf, 36 * 3 * sizeof(float) } });
+    \endcode
+
+    Note how the index defined by \c {startBinding + i}, where \c i is the
+    index in the second argument of
+    \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()}, matches the
+    index of the corresponding entry in the \c bindings vector of the
+    QRhiVertexInputLayout.
+
+    \note the stride must always be a multiple of 4.
+
+    \sa QRhiCommandBuffer::setVertexInput()
  */
 
 /*!
@@ -352,6 +425,69 @@ QT_BEGIN_NAMESPACE
     \class QRhiVertexInputLayout::Attribute
     \inmodule QtRhi
     \brief Describes a single vertex input element.
+
+    The members specify the binding number, location, format, and offset for a
+    single vertex input element.
+
+    \note For HLSL it is assumed that the vertex shader uses
+    \c{TEXCOORD<location>} as the semantic for each input. Hence no separate
+    semantic name and index.
+
+    As an example, assume a vertex shader with the following inputs:
+
+    \badcode
+        layout(location = 0) in vec4 position;
+        layout(location = 1) in vec2 texcoord;
+    \endcode
+
+    Now let's assume that we have 3 component vertex positions \c{(x, y, z)}
+    and 2 component texture coordinates \c{(u, v)} are provided in a
+    non-interleaved format in a buffer (or separate buffers even). Once two
+    bindings are defined, the attributes could be specified as:
+
+    \badcode
+        QRhiVertexInputLayout inputLayout;
+        inputLayout.bindings = {
+            { 3 * sizeof(float) },
+            { 2 * sizeof(float) }
+        };
+        inputLayout.attributes = {
+            { 0, 0, QRhiVertexInputLayout::Attribute::Float3, 0 },
+            { 1, 1, QRhiVertexInputLayout::Attribute::Float2, 0 }
+        };
+    \endcode
+
+    Once a graphics pipeline with this vertex input layout is bound, the vertex
+    inputs could be set up like the following for drawing a cube with 36
+    vertices, assuming we have a single buffer with first the positions and
+    then the texture coordinates:
+
+    \badcode
+        cb->setVertexInput(0, { { cubeBuf, 0 }, { cubeBuf, 36 * 3 * sizeof(float) } });
+    \endcode
+
+    When working with interleaved data, there will typically be just one
+    binding, with multiple attributes refering to that same buffer binding
+    point:
+
+    \badcode
+        QRhiVertexInputLayout inputLayout;
+        inputLayout.bindings = {
+            { 5 * sizeof(float) }
+        };
+        inputLayout.attributes = {
+            { 0, 0, QRhiVertexInputLayout::Attribute::Float3, 0 },
+            { 0, 1, QRhiVertexInputLayout::Attribute::Float2, 3 * sizeof(float) }
+        };
+    \endcode
+
+    and then:
+
+    \badcode
+        cb->setVertexInput(0, { { interleavedCubeBuf, 0 } });
+    \endcode
+
+    \sa QRhiCommandBuffer::setVertexInput()
  */
 
 /*!
@@ -371,6 +507,9 @@ QT_BEGIN_NAMESPACE
     \class QRhiGraphicsShaderStage
     \inmodule QtRhi
     \brief Specifies the type and the shader code for a shader stage in the graphics pipeline.
+
+    \note There is no geometry stage because some graphics APIs (Metal) have no support
+    for it.
  */
 
 /*!
@@ -1084,7 +1223,7 @@ QT_BEGIN_NAMESPACE
     \value NoVSync Requests disabling waiting for vertical sync, also avoiding
     throttling the rendering thread. The behavior is backend specific and
     applicable only where it is possible to control this. Some may ignore the
-    request altogether. For OpenGL, use QSurfaceFormat::setSwapInterval().
+    request altogether. For OpenGL, use QSurfaceFormat::setSwapInterval() instead.
  */
 
 /*!

src/rhi/qrhi.h

@@ -60,22 +60,6 @@ class QRhiResourceUpdateBatch;
 struct QRhiResourceUpdateBatchPrivate;
 class QRhiProfiler;
 
-// C++ object ownership rules:
-//   1. new*() and create() return value owned by the caller.
-//   2. next*() return value not owned by the caller.
-//   3. Passing a pointer via set*() or the structs does not transfer ownership.
-//   4. release() does not destroy the C++ object. releaseAndDestroy() does, and is equivalent to o->release(); delete o;
-//
-// Graphics resource ownership rules:
-//   1. new*() does not create underlying graphics resources. build() does.
-//   2. Except: new*Descriptor() implicitly "builds". (no build() for QRhiRenderPassDescriptor f.ex.)
-//   3. release() schedules graphics resources for destruction. The C++ object is reusable immediately via build(), or can be destroyed.
-//   4. build() on an already built object calls release() implicitly. Except swapchains. (buildOrResize() - special semantics)
-//   5. Ownership of resources imported (QRhi*InitParams or buildFrom()) or exported (nativeHandles()) is never taken or given away.
-//
-// Other:
-//   1. QRhiResourceUpdateBatch manages no graphics resources underneath. begin/endPass() implicitly calls release() on the batch.
-
 struct Q_RHI_EXPORT QRhiColorClearValue
 {
     QRhiColorClearValue() : rgba(0, 0, 0, 1) { }
@@ -101,8 +85,6 @@ struct Q_RHI_EXPORT QRhiViewport
     QRhiViewport()
         : r(0, 0, 1280, 720), minDepth(0), maxDepth(1)
     { }
-    // x,y is bottom-left, like in OpenGL, regardless of what isYUpInFramebuffer() says.
-    // Depth range defaults to 0..1. See clipSpaceCorrMatrix().
     QRhiViewport(float x, float y, float w, float h, float minDepth_ = 0.0f, float maxDepth_ = 1.0f)
         : r(x, y, w, h), minDepth(minDepth_), maxDepth(maxDepth_)
     { }
@@ -116,7 +98,6 @@ Q_DECLARE_TYPEINFO(QRhiViewport, Q_MOVABLE_TYPE);
 struct Q_RHI_EXPORT QRhiScissor
 {
     QRhiScissor() { }
-    // x,y is bottom-left, like in OpenGL, regardless of what isYUpInFramebuffer() says
     QRhiScissor(int x, int y, int w, int h)
         : r(x, y, w, h)
     { }
@@ -136,7 +117,7 @@ struct Q_RHI_EXPORT QRhiVertexInputLayout
         Binding(quint32 stride_, Classification cls = PerVertex, int stepRate = 1)
             : stride(stride_), classification(cls), instanceStepRate(stepRate)
         { }
-        quint32 stride; // must be a multiple of 4
+        quint32 stride;
         Classification classification;
         int instanceStepRate;
     };
@@ -156,14 +137,12 @@ struct Q_RHI_EXPORT QRhiVertexInputLayout
             : binding(binding_), location(location_), format(format_), offset(offset_)
         { }
         int binding;
-        // With HLSL we assume the vertex shader uses TEXCOORD<location> as the
-        // semantic for each input. Hence no separate semantic name and index.
         int location;
         Format format;
         quint32 offset;
     };
 
-    QVector<Binding> bindings; // slots
+    QVector<Binding> bindings;
     QVector<Attribute> attributes;
 };
 
@@ -176,9 +155,8 @@ struct Q_RHI_EXPORT QRhiGraphicsShaderStage
     enum Type {
         Vertex,
         Fragment,
-        TessellationControl, // Hull
-        TessellationEvaluation // Domain
-        // yes, no geometry shaders (Metal does not have them)
+        TessellationControl,
+        TessellationEvaluation
     };
 
     QRhiGraphicsShaderStage() { }
@@ -208,10 +186,7 @@ struct Q_RHI_EXPORT QRhiShaderResourceBinding
     Q_DECLARE_FLAGS(StageFlags, StageFlag)
 
     static QRhiShaderResourceBinding uniformBuffer(int binding_, StageFlags stage_, QRhiBuffer *buf_);
-
-    // Bind a region only. Up to the user to ensure offset is aligned to ubufAlignment.
     static QRhiShaderResourceBinding uniformBuffer(int binding_, StageFlags stage_, QRhiBuffer *buf_, int offset_, int size_);
-
     static QRhiShaderResourceBinding sampledTexture(int binding_, StageFlags stage_, QRhiTexture *tex_, QRhiSampler *sampler_);
 
     int binding;

src/rhi/qrhiprofiler.cpp

@@ -140,6 +140,32 @@ QT_BEGIN_NAMESPACE
     \value FrameBuildTime CPU beginFrame-endFrame times
  */
 
+/*!
+    \class QRhiProfiler::CpuTime
+    \inmodule QtRhi
+    \brief Contains CPU-side frame timings.
+
+    Once sufficient number of frames have been rendered, the minimum, maximum,
+    and average values (in milliseconds) from various measurements are made
+    available in this struct queriable from QRhiProfiler::frameToFrameTimes()
+    and QRhiProfiler::frameBuildTimes().
+
+    \sa QRhiProfiler::setFrameTimingWriteInterval()
+ */
+
+/*!
+    \class QRhiProfiler::GpuTime
+    \inmodule QtRhi
+    \brief Contains GPU-side frame timings.
+
+    Once sufficient number of frames have been rendered, the minimum, maximum,
+    and average values (in milliseconds) calculated from GPU command buffer
+    timestamps are made available in this struct queriable from
+    QRhiProfiler::gpuFrameTimes().
+
+    \sa QRhiProfiler::setFrameTimingWriteInterval()
+ */
+
 /*!
     \internal
  */

tests/manual/shadertools/oneshaderthreecontexts_prebaked/main.cpp

@@ -130,8 +130,8 @@ int main(int argc, char **argv)
     // Vulkan
 #if QT_CONFIG(vulkan)
     QVulkanInstance inst;
-    const QByteArray vsSpv = vs.shader(QBakedShader::ShaderKey(QBakedShader::SpirvShader)).shader;
-    const QByteArray fsSpv = fs.shader(QBakedShader::ShaderKey(QBakedShader::SpirvShader)).shader;
+    const QByteArray vsSpv = vs.shader({ QBakedShaderKey::SpirvShader, QBakedShaderVersion(100) }).shader();
+    const QByteArray fsSpv = fs.shader({ QBakedShaderKey::SpirvShader, QBakedShaderVersion(100) }).shader();
     VulkanWindow vkw(vsSpv, fsSpv);
     if (inst.create()) {
         vkw.setVulkanInstance(&inst);

tests/manual/shadertools/oneshaderthreecontexts_prebaked/renderwindow.cpp

@@ -102,14 +102,14 @@ void RenderWindow::init()
     if (!es && format.profile() == QSurfaceFormat::CoreProfile)
         version = 330;
 
-    QBakedShader::ShaderSourceVersion::Flags flags = 0;
+    QBakedShaderVersion::Flags flags = 0;
     if (es) {
         version = 100;
-        flags |= QBakedShader::ShaderSourceVersion::GlslEs;
+        flags |= QBakedShaderVersion::GlslEs;
     }
 
-    const QByteArray vertexShaderSource = m_vs.shader(QBakedShader::ShaderKey(QBakedShader::GlslShader, QBakedShader::ShaderSourceVersion(version, flags))).shader;
-    const QByteArray fragmentShaderSource = m_fs.shader(QBakedShader::ShaderKey(QBakedShader::GlslShader, QBakedShader::ShaderSourceVersion(version, flags))).shader;
+    const QByteArray vertexShaderSource = m_vs.shader(QBakedShaderKey(QBakedShaderKey::GlslShader, QBakedShaderVersion(version, flags))).shader();
+    const QByteArray fragmentShaderSource = m_fs.shader(QBakedShaderKey(QBakedShaderKey::GlslShader, QBakedShaderVersion(version, flags))).shader();
 
     if (!m_program->addShaderFromSourceCode(QOpenGLShader::Vertex, vertexShaderSource)) {
         emit error(m_program->log());