Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
What's new
10
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Open sidebar
Laszlo Agocs
qtrhi
Commits
70403f3d
Commit
70403f3d
authored
Jan 18, 2019
by
Laszlo Agocs
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Clean up qrhi.h by moving everything to proper docs
parent
31db4910
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
189 additions
and
79 deletions
+189
-79
src/rhi/qrhi.cpp
src/rhi/qrhi.cpp
+164
-18
src/rhi/qrhi.h
src/rhi/qrhi.h
+25
-61
No files found.
src/rhi/qrhi.cpp
View file @
70403f3d
...
...
@@ -223,6 +223,13 @@ QT_BEGIN_NAMESPACE
QRhiTexture::nativeHandles(). Most importantly, passing pointers in structs
and via setters does not transfer ownership.
\section3 Threading
A QRhi instance can be created and used on any thread but all usage must be
limited to that one single thread. When it comes to native objects, such as
OpenGL contexts, passed in in QRhiInitParams, it is up to the application
to ensure they are not misused by other threads.
\sa {Qt Shader Tools}
*/
...
...
@@ -275,24 +282,25 @@ QT_BEGIN_NAMESPACE
\enum QRhi::Feature
Flag values to indicate what features are supported by the backend currently in use.
\value MultisampleTexture
T
extures with sample count larger
than 1 are
supported.
\value MultisampleTexture
Indicates that t
extures with
a
sample count larger
than 1 are
supported.
\value MultisampleRenderBuffer
R
enderbuffers with sample
count larger than
1 are supported.
\value MultisampleRenderBuffer
Indicates that r
enderbuffers with
a
sample
count larger than
1 are supported.
\value DebugMarkers
D
ebug marker groups (and so
\value DebugMarkers
Indicates that d
ebug marker groups (and so
QRhiCommandBuffer::debugMarkBegin()) are supported.
\value Timestamps
C
ommand buffer timestamps are supported.
Relevant for
QRhiProfiler::gpuFrameTimes().
\value Timestamps
Indicates that c
ommand buffer timestamps are supported.
Relevant for
QRhiProfiler::gpuFrameTimes().
\value Instancing Instanced drawing is supported.
\value Instancing In
dicates that in
stanced drawing is supported.
\value CustomInstanceStepRate Instance step rate other than 1 is supported.
\value CustomInstanceStepRate Indicates that instance step rates other than
1 are supported.
\value PrimitiveRestart
R
estarting the assembly of
primitives when
encountering an index value of 0xFFFF
\value PrimitiveRestart
Indicates that r
estarting the assembly of
primitives when
encountering an index value of 0xFFFF
(\l{QRhiCommandBuffer::IndexUInt16}{IndexUInt16}) or 0xFFFFFFFF
(\l{QRhiCommandBuffer::IndexUInt32}{IndexUInt32}) is always enabled, for
certain primitive topologies at least. Due to the wildly varying primitive
...
...
@@ -573,18 +581,54 @@ QT_BEGIN_NAMESPACE
\class QRhiTextureRenderTargetDescription
\inmodule QtRhi
\brief Describes the color and depth or depth/stencil attachments of a render target.
A texture render target has zero or more textures as color attachments,
zero or one renderbuffer as combined depth/stencil buffer or zero or one
texture as depth buffer.
\note \l depthStencilBuffer and \l depthTexture cannot be both set.
*/
/*!
\class QRhiTextureRenderTargetDescription::ColorAttachment
\inmodule QtRhi
\brief Describes the color attachments of a render target.
\brief Describes the a single color attachment of a render target.
A color attachment is either a QRhiTexture or a QRhiRenderBuffer. The
former, when \l texture is set, is used in most cases.
\note \l texture and \l renderBuffer cannot be both set.
Setting renderBuffer instead is recommended only when multisampling is
needed. Relying on QRhi::MultisampleRenderBuffer is a better choice than
QRhi::MultisampleTexture in practice since the former is available in more
run time configurations (e.g. when running on OpenGL ES 3.0 which has no
support for multisample textures, but does support multisample
renderbuffers).
When targeting a non-multisample texture, the \l layer and \l level
indicate the targeted layer (face index \c{0-5} for cubemaps) and mip
level.
When \l texture or \l renderBuffer is multisample, \l resolveTexture can be
set optionally. When set, samples are resolved automatically into that
(non-multisample) texture at the end of the render pass. When rendering
into a multisample renderbuffers, this is the only way to get resolved,
non-multisample content out of them. Multisample textures allow sampling in
shaders so for them this is just one option.
\note when resolving is enabled, the multisample data may not be written
out at all. This means that the multisample \l texture must not be used
afterwards with shaders for sampling when \l resolveTexture is set.
*/
/*!
\class QRhiTextureUploadDescription
\inmodule QtRhi
\brief Describes a texture upload operation.
\note Cubemaps have one layer for each of the six faces in the order +X,
-X, +Y, -Y, +Z, -Z.
*/
/*!
...
...
@@ -597,24 +641,73 @@ QT_BEGIN_NAMESPACE
\class QRhiTextureUploadDescription::Layer::MipLevel
\inmodule QtRhi
\brief Describes one mip level in a layer in a texture upload operation.
The source content is specified either as a QImage or as a raw blob. The
former is only allowed for uncompressed textures, while the latter is only
supported for compressed ones.
\note \l image and \l compressedData cannot be both set.
\l destinationTopLeft specifies the top-left corner of the target
rectangle. Defaults to (0, 0).
An empty \l sourceSize (the default) indicates that size is assumed to be
the size of the subresource. For uncompressed textures this implies that
the size of the source \l image must match the subresource. For compressed
textures sufficient amount of data must be provided in \l compressedData.
\note With compressed textures the first upload must always match the
subresource size due to graphics API limitations with some backends.
\l sourceTopLeft is is only supported for uncompressed textures, and
specifies the top-left corner of the source rectangle.
\note Setting \l sourceSize or \l sourceTopLeft may trigger a QImage copy
internally, depending on the format and the backend.
*/
/*!
\class QRhiTextureCopyDescription
\inmodule QtRhi
\brief Describes a texture-to-texture copy operation.
An empty \l pixelSize (the default) indicates that the entire subresource
is to be copied.
\note The source texture must be created with
QRhiTexture::UsedAsTransferSource.
*/
/*!
\class QRhiReadbackDescription
\inmodule QtRhi
\brief Describes a readback (reading back texture contents from possibly GPU-only memory) operation.
The source of the readback operation is either a QRhiTexture or the
current backbuffer of the currently targeted QRhiSwapChain. When \l
texture is not set, the swapchain is used. Otherwise the specified
QRhiTexture is treated as the source.
\note Textures used in readbacks must be created with
QRhiTexture::UsedAsTransferSource.
\note Swapchains used in readbacks must be created with
QRhiSwapChain::UsedAsTransferSource.
\l layer and \l level are only applicable when the source is a QRhiTexture.
\note Multisample textures cannot be read back. Readbacks are supported for
multisample swapchain buffers however.
*/
/*!
\class QRhiReadbackResult
\inmodule QtRhi
\brief Describes the results of a potentially asynchronous readback operation.
When \l completed is set, the function is invoked when the \l data is
available. \l format and \l pixelSize are set upon completion together with
\l data.
*/
/*!
...
...
@@ -635,6 +728,20 @@ QT_BEGIN_NAMESPACE
\brief Vertex, index, or uniform (constant) buffer resource.
*/
/*!
\fn void QRhiBuffer::setSize(int sz)
Sets the size of the buffer in bytes. The size is normally specified in
QRhi::newBuffer() so this function is only used when the size has to be
changed. As with other setters, the size only takes effect when calling
build(), and for already built buffers this involves releasing the previous
native resource and creating new ones under the hood.
Backends may choose to allocate buffers bigger than \a sz in order to
fulfill alignment requirements. This is hidden from the applications and
size() will always report the size requested in \a sz.
*/
/*!
\enum QRhiBuffer::Type
Specifies type of buffer resource.
...
...
@@ -868,7 +975,12 @@ QT_BEGIN_NAMESPACE
/*!
\enum QRhiTextureRenderTarget::Flag
Flag values describing the load/store behavior for the render target
Flag values describing the load/store behavior for the render target. The
load/store behavior may be baked into native resources under the hood,
depending on the backend, and therefore it needs to be known upfront and
cannot be changed without rebuilding (and so releasing and creating new
native resources).
\value PreserveColorContents Indicates that the contents of the color
attachments is to be loaded when starting a render pass, instead of
...
...
@@ -957,6 +1069,39 @@ QT_BEGIN_NAMESPACE
\class QRhiGraphicsPipeline
\inmodule QtRhi
\brief Graphics pipeline state resource.
\note Setting the shader resource bindings is mandatory but the referenced
QRhiShaderResourceBindings is not required to be built when build() is
called. Instead, QRhiShaderResourceBindings::build() must be done at latest
before QRhiCommandBuffer::setGraphicsPipeline().
\note Setting the render pass descriptor is mandatory. To obtain a
QRhiRenderPassDescriptor that can be passed to setRenderPassDescriptor(),
use either QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor() or
QRhiSwapChain::newCompatibleRenderPassDescriptor().
\note Setting the vertex input layout is mandatory.
\note Setting the shader stages is mandatory.
\note sampleCount() defaults to 1 and must match the sample count of the
render target's color and depth stencil attachments.
\note The depth test, depth write, and stencil test are disabled by
default.
\note stencilReadMask() and stencilWriteMask() apply to both faces. They
both default to 0xFF.
*/
/*!
\fn void QRhiGraphicsPipeline::setTargetBlends(const QVector<TargetBlend> &blends)
Sets the blend specification for color attachments. Each element in \a
blends corresponds to a color attachment of the render target.
By default no blends are set, which is a shortcut to disabling blending and
enabling color write for all four channels.
*/
/*!
...
...
@@ -1084,11 +1229,6 @@ QT_BEGIN_NAMESPACE
Defaults to color write enabled, blending disabled. The blend values are
set up for pre-multiplied alpha (One, OneMinusSrcAlpha, One,
OneMinusSrcAlpha) by default.
Not having any TargetBlend specified in
QRhiGraphicsPipeline::setTargetBlends() disables blending and is a
convenient shortcut when having only one color attachment and no blending
is desired. Otherwise a TargetBlend for each color attachment is expected.
*/
/*!
...
...
@@ -1563,6 +1703,9 @@ QRhiTextureRenderTarget::QRhiTextureRenderTarget(QRhiImplementation *rhi,
the render pass descriptor so those can differ in the two
QRhiTextureRenderTarget intances.
\note resources, such as QRhiTexture instances, referenced in description()
must already be built
\sa build()
*/
...
...
@@ -1583,6 +1726,9 @@ QRhiTextureRenderTarget::QRhiTextureRenderTarget(QRhiImplementation *rhi,
same number and type of attachments (the actual textures can differ) and
the same flags.
\note resources, such as QRhiTexture instances, referenced in description()
must already be built
\return \c true when successful, \c false when a graphics operation failed.
Regardless of the return value, calling release() is always safe.
*/
...
...
src/rhi/qrhi.h
View file @
70403f3d
...
...
@@ -214,25 +214,17 @@ struct Q_RHI_EXPORT QRhiTextureRenderTargetDescription
{
struct
Q_RHI_EXPORT
ColorAttachment
{
ColorAttachment
()
{
}
// either a texture or a renderbuffer
ColorAttachment
(
QRhiTexture
*
texture_
)
:
texture
(
texture_
)
{
}
ColorAttachment
(
QRhiRenderBuffer
*
renderBuffer_
)
:
renderBuffer
(
renderBuffer_
)
{
}
QRhiTexture
*
texture
=
nullptr
;
QRhiRenderBuffer
*
renderBuffer
=
nullptr
;
// for texture
int
layer
=
0
;
// face (0..5) for cubemaps
int
level
=
0
;
// only when non-multisample
int
layer
=
0
;
int
level
=
0
;
// When texture or renderBuffer is multisample. Optional. When set,
// samples are resolved into this non-multisample texture. Note that
// the msaa data may not be written out at all in this case. This is
// the only way to get a non-msaa texture from an msaa render target as
// we do not have an explicit resolve operation because it does not
// exist in some APIs and would not be efficient with tiled GPUs anyways.
QRhiTexture
*
resolveTexture
=
nullptr
;
int
resolveLayer
=
0
;
// unused for now since cubemaps cannot be multisample
int
resolveLayer
=
0
;
int
resolveLevel
=
0
;
};
...
...
@@ -248,7 +240,6 @@ struct Q_RHI_EXPORT QRhiTextureRenderTargetDescription
{
colorAttachments
.
append
(
colorAttachment
);
}
QVector
<
ColorAttachment
>
colorAttachments
;
// depth-stencil is is a renderbuffer, a texture, or none
QRhiRenderBuffer
*
depthStencilBuffer
=
nullptr
;
QRhiTexture
*
depthTexture
=
nullptr
;
};
...
...
@@ -261,7 +252,6 @@ struct Q_RHI_EXPORT QRhiTextureUploadDescription
struct
Q_RHI_EXPORT
Layer
{
struct
Q_RHI_EXPORT
MipLevel
{
MipLevel
()
{
}
// either a QImage or compressed data (not both)
MipLevel
(
const
QImage
&
image_
)
:
image
(
image_
)
{
}
MipLevel
(
const
QByteArray
&
compressedData_
)
:
compressedData
(
compressedData_
)
{
}
...
...
@@ -269,19 +259,7 @@ struct Q_RHI_EXPORT QRhiTextureUploadDescription
QByteArray
compressedData
;
QPoint
destinationTopLeft
;
// Empty = entire subresource. For uncompressed this then means the
// size of the source image must match the subresource. When
// non-empty, this size is used.
//
// Works for compressed as well, but the first compressed upload
// must always match the subresource size (and sourceSize can be
// left unset) due to gfx api limitations with some backends.
QSize
sourceSize
;
// This is only supported for uncompressed. Setting sourceSize or
// sourceTopLeft may trigger a QImage copy internally (depending on
// the format and the gfx api).
QPoint
sourceTopLeft
;
};
...
...
@@ -292,7 +270,7 @@ struct Q_RHI_EXPORT QRhiTextureUploadDescription
QRhiTextureUploadDescription
()
{
}
QRhiTextureUploadDescription
(
const
QVector
<
Layer
>
&
layers_
)
:
layers
(
layers_
)
{
}
QVector
<
Layer
>
layers
;
// 6 layers for cubemaps, 1 otherwise
QVector
<
Layer
>
layers
;
};
Q_DECLARE_TYPEINFO
(
QRhiTextureUploadDescription
::
Layer
::
MipLevel
,
Q_MOVABLE_TYPE
);
...
...
@@ -301,7 +279,7 @@ Q_DECLARE_TYPEINFO(QRhiTextureUploadDescription, Q_MOVABLE_TYPE);
struct
Q_RHI_EXPORT
QRhiTextureCopyDescription
{
QSize
pixelSize
;
// empty = entire subresource
QSize
pixelSize
;
int
sourceLayer
=
0
;
int
sourceLevel
=
0
;
...
...
@@ -316,10 +294,8 @@ Q_DECLARE_TYPEINFO(QRhiTextureCopyDescription, Q_MOVABLE_TYPE);
struct
Q_RHI_EXPORT
QRhiReadbackDescription
{
QRhiReadbackDescription
()
{
}
// source is the back buffer of the swapchain of the current frame (if the swapchain supports readback)
QRhiReadbackDescription
(
QRhiTexture
*
texture_
)
:
texture
(
texture_
)
{
}
// source is the specified texture
// Note that reading back an msaa image is only supported for swapchains.
// Multisample textures cannot be read back.
QRhiReadbackDescription
()
{
}
QRhiReadbackDescription
(
QRhiTexture
*
texture_
)
:
texture
(
texture_
)
{
}
QRhiTexture
*
texture
=
nullptr
;
int
layer
=
0
;
...
...
@@ -354,9 +330,9 @@ class Q_RHI_EXPORT QRhiBuffer : public QRhiResource
{
public:
enum
Type
{
Immutable
,
// data never changes after initial upload - under the hood typically in device local (GPU) memory
Static
,
// data changes infrequently - under the hood typically device local and updated via a separate, host visible staging buffer
Dynamic
// data changes frequently - under the hood typically host visible
Immutable
,
Static
,
Dynamic
};
enum
UsageFlag
{
...
...
@@ -372,8 +348,6 @@ public:
UsageFlags
usage
()
const
{
return
m_usage
;
}
void
setUsage
(
UsageFlags
u
)
{
m_usage
=
u
;
}
// no restrictions here, up to the backend to round up if needed (that
// won't be visible in the user-provided size reported here)
int
size
()
const
{
return
m_size
;
}
void
setSize
(
int
sz
)
{
m_size
=
sz
;
}
...
...
@@ -394,11 +368,11 @@ class Q_RHI_EXPORT QRhiTexture : public QRhiResource
public:
enum
Flag
{
RenderTarget
=
1
<<
0
,
ChangesFrequently
=
1
<<
1
,
// hint for backend to keep staging resources around
ChangesFrequently
=
1
<<
1
,
CubeMap
=
1
<<
2
,
MipMapped
=
1
<<
3
,
sRGB
=
1
<<
4
,
UsedAsTransferSource
=
1
<<
5
,
// will (also) be used as the source of a copy or readback
UsedAsTransferSource
=
1
<<
5
,
UsedWithGenerateMips
=
1
<<
6
};
Q_DECLARE_FLAGS
(
Flags
,
Flag
)
...
...
@@ -474,7 +448,7 @@ class Q_RHI_EXPORT QRhiSampler : public QRhiResource
{
public:
enum
Filter
{
None
,
// for mipmapMode only
None
,
Nearest
,
Linear
};
...
...
@@ -529,7 +503,7 @@ public:
};
enum
Flag
{
UsedWithSwapChainOnly
=
1
<<
0
// use implicit winsys buffers, don't create anything (GL)
UsedWithSwapChainOnly
=
1
<<
0
};
Q_DECLARE_FLAGS
(
Flags
,
Flag
)
...
...
@@ -593,8 +567,6 @@ class Q_RHI_EXPORT QRhiTextureRenderTarget : public QRhiRenderTarget
{
public:
enum
Flag
{
// the load-not-clear request is baked into the resources under the rpd
// with some backends so it cannot be more dynamic than this
PreserveColorContents
=
1
<<
0
,
PreserveDepthStencilContents
=
1
<<
1
};
...
...
@@ -606,12 +578,8 @@ public:
Flags
flags
()
const
{
return
m_flags
;
}
void
setFlags
(
Flags
f
)
{
m_flags
=
f
;
}
// To be called before build() with description and flags set.
// Textures in desc must already be built.
// Note setRenderPassDescriptor() in the base class, that must still be called afterwards (but before build()).
virtual
QRhiRenderPassDescriptor
*
newCompatibleRenderPassDescriptor
()
=
0
;
// as usual, textures in desc must be built before calling build() on the rt
virtual
bool
build
()
=
0
;
protected:
...
...
@@ -654,7 +622,7 @@ public:
Points
};
enum
CullMode
{
// not a bitmask since some apis use a mask, some don't
enum
CullMode
{
None
,
Front
,
Back
...
...
@@ -805,19 +773,19 @@ protected:
Topology
m_topology
=
Triangles
;
CullMode
m_cullMode
=
None
;
FrontFace
m_frontFace
=
CCW
;
QVector
<
TargetBlend
>
m_targetBlends
;
// no blend when empty
QVector
<
TargetBlend
>
m_targetBlends
;
bool
m_depthTest
=
false
;
bool
m_depthWrite
=
false
;
CompareOp
m_depthOp
=
Less
;
bool
m_stencilTest
=
false
;
StencilOpState
m_stencilFront
;
StencilOpState
m_stencilBack
;
quint32
m_stencilReadMask
=
0xFF
;
// applies to both faces
quint32
m_stencilWriteMask
=
0xFF
;
// applies to both faces
int
m_sampleCount
=
1
;
// MSAA, swapchain+depthstencil must match
quint32
m_stencilReadMask
=
0xFF
;
quint32
m_stencilWriteMask
=
0xFF
;
int
m_sampleCount
=
1
;
QVector
<
QRhiGraphicsShaderStage
>
m_shaderStages
;
QRhiVertexInputLayout
m_vertexInputLayout
;
QRhiShaderResourceBindings
*
m_shaderResourceBindings
=
nullptr
;
// must be built by the time ps' build() is called
QRhiShaderResourceBindings
*
m_shaderResourceBindings
=
nullptr
;
QRhiRenderPassDescriptor
*
m_renderPassDesc
=
nullptr
;
void
*
m_reserved
;
};
...
...
@@ -833,8 +801,8 @@ public:
SurfaceHasPreMulAlpha
=
1
<<
0
,
SurfaceHasNonPreMulAlpha
=
1
<<
1
,
sRGB
=
1
<<
2
,
UsedAsTransferSource
=
1
<<
3
,
// will be read back
NoVSync
=
1
<<
4
// may be implementation specific what this results in
UsedAsTransferSource
=
1
<<
3
,
NoVSync
=
1
<<
4
};
Q_DECLARE_FLAGS
(
Flags
,
Flag
)
...
...
@@ -853,8 +821,6 @@ public:
QRhiRenderPassDescriptor
*
renderPassDescriptor
()
const
{
return
m_renderPassDesc
;
}
void
setRenderPassDescriptor
(
QRhiRenderPassDescriptor
*
desc
)
{
m_renderPassDesc
=
desc
;
}
// Alternatively, integrate with an existing swapchain, f.ex.
// QVulkanWindow. Other settings have no effect when this is set.
QObject
*
target
()
const
{
return
m_target
;
}
void
setTarget
(
QObject
*
obj
)
{
m_target
=
obj
;
}
...
...
@@ -891,8 +857,8 @@ public:
void
resourceUpdate
(
QRhiResourceUpdateBatch
*
resourceUpdates
);
void
beginPass
(
QRhiRenderTarget
*
rt
,
const
QRhiColorClearValue
&
colorClearValue
,
// ignored when rt has PreserveColorContents
const
QRhiDepthStencilClearValue
&
depthStencilClearValue
,
// ignored when no ds attachment
const
QRhiColorClearValue
&
colorClearValue
,
const
QRhiDepthStencilClearValue
&
depthStencilClearValue
,
QRhiResourceUpdateBatch
*
resourceUpdates
=
nullptr
);
void
endPass
(
QRhiResourceUpdateBatch
*
resourceUpdates
=
nullptr
);
...
...
@@ -956,7 +922,7 @@ public:
void
uploadStaticBuffer
(
QRhiBuffer
*
buf
,
int
offset
,
int
size
,
const
void
*
data
);
void
uploadStaticBuffer
(
QRhiBuffer
*
buf
,
const
void
*
data
);
void
uploadTexture
(
QRhiTexture
*
tex
,
const
QRhiTextureUploadDescription
&
desc
);
void
uploadTexture
(
QRhiTexture
*
tex
,
const
QImage
&
image
);
// shortcut
void
uploadTexture
(
QRhiTexture
*
tex
,
const
QImage
&
image
);
void
copyTexture
(
QRhiTexture
*
dst
,
QRhiTexture
*
src
,
const
QRhiTextureCopyDescription
&
desc
=
QRhiTextureCopyDescription
());
void
readBackTexture
(
const
QRhiReadbackDescription
&
rb
,
QRhiReadbackResult
*
result
);
void
generateMips
(
QRhiTexture
*
tex
);
...
...
@@ -977,8 +943,6 @@ struct Q_RHI_EXPORT QRhiInitParams
{
};
// A QRhi instance can be created and used on any thread but all usage must be
// limited to that one single thread.
class
Q_RHI_EXPORT
QRhi
{
public:
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment