#include <qrhi_p.h>
Classes | |
| class | NativeTexture |
| Contains information about the underlying native resources of a texture. More... | |
Public Types | |
| enum | Flag { RenderTarget = 1 << 0 , CubeMap = 1 << 2 , MipMapped = 1 << 3 , sRGB = 1 << 4 , UsedAsTransferSource = 1 << 5 , UsedWithGenerateMips = 1 << 6 , UsedWithLoadStore = 1 << 7 , UsedAsCompressedAtlas = 1 << 8 , ExternalOES = 1 << 9 , ThreeDimensional = 1 << 10 , TextureRectangleGL = 1 << 11 , TextureArray = 1 << 12 } |
| enum | Format { UnknownFormat , RGBA8 , BGRA8 , R8 , RG8 , R16 , RG16 , RED_OR_ALPHA8 , RGBA16F , RGBA32F , R16F , R32F , D16 , D24 , D24S8 , D32F , BC1 , BC2 , BC3 , BC4 , BC5 , BC6H , BC7 , ETC2_RGB8 , ETC2_RGB8A1 , ETC2_RGBA8 , ASTC_4x4 , ASTC_5x4 , ASTC_5x5 , ASTC_6x5 , ASTC_6x6 , ASTC_8x5 , ASTC_8x6 , ASTC_8x8 , ASTC_10x5 , ASTC_10x6 , ASTC_10x8 , ASTC_10x10 , ASTC_12x10 , ASTC_12x12 } |
 Public Types inherited from QRhiResource | |
| enum | Type { Buffer , Texture , Sampler , RenderBuffer , RenderPassDescriptor , RenderTarget , TextureRenderTarget , ShaderResourceBindings , GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer } |
Public Member Functions | |
| QRhiResource::Type | resourceType () const override |
| Format | format () const |
| void | setFormat (Format fmt) |
| QSize | pixelSize () const |
| void | setPixelSize (const QSize &sz) |
| int | depth () const |
| void | setDepth (int depth) |
| int | arraySize () const |
| void | setArraySize (int arraySize) |
| Flags | flags () const |
| void | setFlags (Flags f) |
| int | sampleCount () const |
| void | setSampleCount (int s) |
| virtual bool | create ()=0 |
| virtual NativeTexture | nativeTexture () |
| virtual bool | createFrom (NativeTexture src) |
| virtual void | setNativeLayout (int layout) |
| Public Member Functions inherited from QRhiResource | |
| virtual | ~QRhiResource () |
| virtual void | destroy ()=0 |
| void | deleteLater () |
| QByteArray | name () const |
| void | setName (const QByteArray &name) |
| quint64 | globalResourceId () const |
Protected Member Functions | |
| QRhiTexture (QRhiImplementation *rhi, Format format_, const QSize &pixelSize_, int depth_, int arraySize_, int sampleCount_, Flags flags_) | |
| 64-bit integer containing the native object handle. More... | |
| Protected Member Functions inherited from QRhiResource | |
| QRhiResource (QRhiImplementation *rhi) | |
Protected Attributes | |
| Format | m_format |
| QSize | m_pixelSize |
| int | m_depth |
| int | m_arraySize |
| int | m_sampleCount |
| Flags | m_flags |
| Protected Attributes inherited from QRhiResource | |
| QRhiImplementation * | m_rhi = nullptr |
| quint64 | m_id |
| QByteArray | m_objectName |
Detailed Description
Member Enumeration Documentation
◆ Flag
| enum QRhiTexture::Flag |
Flag values to specify how the texture is going to be used. Not honoring the flags set before create() and attempting to use the texture in ways that was not declared upfront can lead to unspecified behavior or decreased performance depending on the backend and the underlying graphics API.
\value RenderTarget The texture going to be used in combination with QRhiTextureRenderTarget.
\value CubeMap The texture is a cubemap. Such textures have 6 layers, one for each face in the order of +X, -X, +Y, -Y, +Z, -Z. Cubemap textures cannot be multisample.
\value MipMapped The texture has mipmaps. The appropriate mip count is calculated automatically and can also be retrieved via QRhi::mipLevelsForSize(). The images for the mip levels have to be provided in the texture uploaded or generated via QRhiResourceUpdateBatch::generateMips(). Multisample textures cannot have mipmaps.
\value sRGB Use an sRGB format.
\value UsedAsTransferSource The texture is used as the source of a texture copy or readback, meaning the texture is given as the source in QRhiResourceUpdateBatch::copyTexture() or QRhiResourceUpdateBatch::readBackTexture().
\value UsedWithGenerateMips The texture is going to be used with QRhiResourceUpdateBatch::generateMips().
\value UsedWithLoadStore The texture is going to be used with image load/store operations, for example, in a compute shader.
\value UsedAsCompressedAtlas The texture has a compressed format and the dimensions of subresource uploads may not match the texture size.
\value ExternalOES The texture should use the GL_TEXTURE_EXTERNAL_OES target with OpenGL. This flag is ignored with other graphics APIs.
\value ThreeDimensional The texture is a 3D texture. Such textures should be created with the QRhi::newTexture() overload taking a depth in addition to width and height. A 3D texture can have mipmaps but cannot be multisample. When rendering into, or uploading data to a 3D texture, the layer specified in the render target's color attachment or the upload description refers to a single slice in range [0..depth-1]. The underlying graphics API may not support 3D textures at run time. Support is indicated by the QRhi::ThreeDimensionalTextures feature.
\value TextureRectangleGL The texture should use the GL_TEXTURE_RECTANGLE target with OpenGL. This flag is ignored with other graphics APIs. Just like ExternalOES, this flag is useful when working with platform APIs where native OpenGL texture objects received from the platform are wrapped in a QRhiTexture, and the platform can only provide textures for a non-2D texture target.
\value TextureArray The texture is a texture array, i.e. a single texture object that is a homogeneous array of 2D textures. Texture arrays are created with QRhi::newTextureArray(). The underlying graphics API may not support texture array objects at run time. Support is indicated by the QRhi::TextureArrays feature. When rendering into, or uploading data to a texture array, the layer specified in the render target's color attachment or the upload description selects a single element in the array.
| Enumerator | |
|---|---|
| RenderTarget | |
| CubeMap | |
| MipMapped | |
| sRGB | |
| UsedAsTransferSource | |
| UsedWithGenerateMips | |
| UsedWithLoadStore | |
| UsedAsCompressedAtlas | |
| ExternalOES | |
| ThreeDimensional | |
| TextureRectangleGL | |
| TextureArray | |
◆ Format
| enum QRhiTexture::Format |
Specifies the texture format. See also QRhi::isTextureFormatSupported() and note that flags() can modify the format when QRhiTexture::sRGB is set.
\value UnknownFormat Not a valid format. This cannot be passed to setFormat().
\value RGBA8 Four component, unsigned normalized 8 bit per component. Always supported.
\value BGRA8 Four component, unsigned normalized 8 bit per component.
\value R8 One component, unsigned normalized 8 bit.
\value RG8 Two components, unsigned normalized 8 bit.
\value R16 One component, unsigned normalized 16 bit.
\value RG16 Two component, unsigned normalized 16 bit.
\value RED_OR_ALPHA8 Either same as R8, or is a similar format with the component swizzled to alpha, depending on \l{QRhi::RedOrAlpha8IsRed}{RedOrAlpha8IsRed}.
\value RGBA16F Four components, 16-bit float per component.
\value RGBA32F Four components, 32-bit float per component.
\value D16 16-bit depth (normalized unsigned integer)
\value D24 24-bit depth (normalized unsigned integer)
\value D24S8 24-bit depth (normalized unsigned integer), 8 bit stencil
\value D32F 32-bit depth (32-bit float)
\value BC1 \value BC2 \value BC3 \value BC4 \value BC5 \value BC6H \value BC7
\value ETC2_RGB8 \value ETC2_RGB8A1 \value ETC2_RGBA8
\value ASTC_4x4 \value ASTC_5x4 \value ASTC_5x5 \value ASTC_6x5 \value ASTC_6x6 \value ASTC_8x5 \value ASTC_8x6 \value ASTC_8x8 \value ASTC_10x5 \value ASTC_10x6 \value ASTC_10x8 \value ASTC_10x10 \value ASTC_12x10 \value ASTC_12x12
Constructor & Destructor Documentation
◆ QRhiTexture()
|
protected |
64-bit integer containing the native object handle.
\variable QRhiTexture::NativeTexture::object
With OpenGL, the native handle is a GLuint value, so object can then be cast to a GLuint. With Vulkan, the native handle is a VkImage, so object can be cast to a VkImage. With Direct3D 11 and Metal object contains a ID3D11Texture2D or MTLTexture pointer, respectively.
\variable QRhiTexture::NativeTexture::layout
Specifies the current image layout for APIs like Vulkan.
For Vulkan, layout contains a VkImageLayout value.
Member Function Documentation
◆ arraySize()
◆ create()
|
pure virtual |
Creates the corresponding native graphics resources. If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.
- Returns
truewhen successful,falsewhen a graphics operation failed. Regardless of the return value, calling destroy() is always safe.
Implemented in QVkTexture, QNullTexture, QMetalTexture, QGles2Texture, and QD3D11Texture.
◆ createFrom()
|
virtual |
Similar to create() except that no new native textures are created. Instead, the native texture resources specified by src is used.
This allows importing an existing native texture object (which must belong to the same device or sharing context, depending on the graphics API) from an external graphics engine.
- Note
- format(), pixelSize(), sampleCount(), and flags() must still be set correctly. Passing incorrect sizes and other values to QRhi::newTexture() and then following it with a createFrom() expecting that the native texture object alone is sufficient to deduce such values is wrong and will lead to problems.
- QRhiTexture does not take ownership of the texture object. destroy() does not free the object or any associated memory.
The opposite of this operation, exposing a QRhiTexture-created native texture object to a foreign engine, is possible via nativeTexture().
- Note
- When importing a 3D texture, or a texture array object, or, with OpenGL ES, an external texture, it is then especially important to set the corresponding flags (ThreeDimensional, TextureArray, ExternalOES) via setFlags() before calling this function.
Reimplemented in QVkTexture, QNullTexture, QMetalTexture, QGles2Texture, and QD3D11Texture.
Definition at line 2660 of file qrhi.cpp.
◆ depth()
|
inline |
◆ flags()
|
inline |
◆ format()
|
inline |
◆ nativeTexture()
|
virtual |
- Returns
- the underlying native resources for this texture. The returned value will be empty if exposing the underlying native resources is not supported by the backend.
- See also
- createFrom()
Reimplemented in QVkTexture, QMetalTexture, QGles2Texture, and QD3D11Texture.
◆ pixelSize()
|
inline |
◆ resourceType()
|
overridevirtual |
◆ sampleCount()
◆ setArraySize()
◆ setDepth()
◆ setFlags()
◆ setFormat()
◆ setNativeLayout()
|
virtual |
With some graphics APIs, such as Vulkan, integrating custom rendering code that uses the graphics API directly needs special care when it comes to image layouts. This function allows communicating the expected layout the image backing the QRhiTexture is in after the native rendering commands.
For example, consider rendering into a QRhiTexture's VkImage directly with Vulkan in a code block enclosed by QRhiCommandBuffer::beginExternal() and QRhiCommandBuffer::endExternal(), followed by using the image for texture sampling in a QRhi-based render pass. To avoid potentially incorrect image layout transitions, this function can be used to indicate what the image layout will be once the commands recorded in said code block complete.
Calling this function makes sense only after QRhiCommandBuffer::endExternal() and before a subsequent QRhiCommandBuffer::beginPass().
This function has no effect with QRhi backends where the underlying graphics API does not expose a concept of image layouts.
Reimplemented in QVkTexture.
Definition at line 2686 of file qrhi.cpp.
◆ setPixelSize()
◆ setSampleCount()
|
inline |
Member Data Documentation
◆ m_arraySize
◆ m_depth
◆ m_flags
◆ m_format
◆ m_pixelSize
◆ m_sampleCount
The documentation for this class was generated from the following files:
