QOpenGLTexture Class

  // Prepare texture
  QOpenGLTexture *texture = new QOpenGLTexture(QImage(fileName).mirrored());
  texture->setMinificationFilter(QOpenGLTexture::LinearMipMapLinear);
  texture->setMagnificationFilter(QOpenGLTexture::Linear);
  ...
  // Render with texture
  texture->bind();
  glDrawArrays(...);

Member Function Documentation

QOpenGLTexture::QOpenGLTexture(Target target)

Creates a QOpenGLTexture object that can later be bound to target.

This does not create the underlying OpenGL texture object. Therefore, construction using this constructor does not require a valid current OpenGL context.

QOpenGLTexture::QOpenGLTexture(const QImage &image, MipMapGeneration genMipMaps = GenerateMipMaps)

Creates a QOpenGLTexture object that can later be bound to the 2D texture target and contains the pixel data contained in image. If you wish to have a chain of mipmaps generated then set genMipMaps to true (this is the default).

This does create the underlying OpenGL texture object. Therefore, construction using this constructor does require a valid current OpenGL context.

QOpenGLTexture::~QOpenGLTexture()

Destroys the instance of QOpenGLTexture.

void QOpenGLTexture::allocateStorage()

Allocates server-side storage for this texture object taking into account, the format, dimensions, mipmap levels, array layers and cubemap faces.

Once storage has been allocated it is no longer possible to change these properties.

If supported QOpenGLTexture makes use of immutable texture storage.

Once storage has been allocated for the texture then pixel data can be uploaded via one of the setData() overloads.

Note: If immutable texture storage is not available, then a default pixel format and pixel type will be used to create the mutable storage. You can use the other allocateStorage() overload to specify exactly the pixel format and the pixel type to use when allocating mutable storage; this is particulary useful under certain OpenGL ES implementations (notably, OpenGL ES 2), where the pixel format and the pixel type used at allocation time must perfectly match the format and the type passed to any subsequent setData() call.

See also isStorageAllocated() and setData().

void QOpenGLTexture::allocateStorage(PixelFormat pixelFormat, PixelType pixelType)

Allocates server-side storage for this texture object taking into account, the format, dimensions, mipmap levels, array layers and cubemap faces.

Once storage has been allocated it is no longer possible to change these properties.

If supported QOpenGLTexture makes use of immutable texture storage. However, if immutable texture storage is not available, then the specified pixelFormat and pixelType will be used to allocate mutable storage; note that in certain OpenGL implementations (notably, OpenGL ES 2) they must perfectly match the format and the type passed to any subsequent setData() call.

Once storage has been allocated for the texture then pixel data can be uploaded via one of the setData() overloads.

This function was introduced in Qt 5.5.

See also isStorageAllocated() and setData().

void QOpenGLTexture::bind()

Binds this texture to the currently active texture unit ready for rendering. Note that you do not need to bind QOpenGLTexture objects in order to modify them as the implementation makes use of the EXT_direct_state_access extension where available and simulates it where it is not.

See also release().

void QOpenGLTexture::bind(uint unit, TextureUnitReset reset = DontResetTextureUnit)

Binds this texture to texture unit unit ready for rendering. Note that you do not need to bind QOpenGLTexture objects in order to modify them as the implementation makes use of the EXT_direct_state_access extension where available and simulates it where it is not.

If parameter reset is true then this function will restore the active unit to the texture unit that was active upon entry.

See also release().

QColor QOpenGLTexture::borderColor() const

Returns the borderColor of this texture.

See also setBorderColor().

void QOpenGLTexture::borderColor(float *border) const

Writes the texture border color into the first four elements of the array pointed to by border.

See also setBorderColor().

void QOpenGLTexture::borderColor(int *border) const

Writes the texture border color into the first four elements of the array pointed to by border.

This is an overloaded function.

void QOpenGLTexture::borderColor(unsigned int *border) const

Writes the texture border color into the first four elements of the array pointed to by border.

This is an overloaded function.

[static] GLuint QOpenGLTexture::boundTextureId(BindingTarget target)

Returns the textureId of the texture that is bound to the target of the currently active texture unit.

[static] GLuint QOpenGLTexture::boundTextureId(uint unit, BindingTarget target)

Returns the textureId of the texture that is bound to the target of the texture unit unit.

ComparisonFunction QOpenGLTexture::comparisonFunction() const

Returns the texture comparison operator set on this texture. By default, a texture has a CompareLessEqual comparison function.

This function was introduced in Qt 5.5.

See also setComparisonFunction().

ComparisonMode QOpenGLTexture::comparisonMode() const

Returns the texture comparison mode set on this texture. By default, a texture has a CompareNone comparison mode (i.e. comparisons are disabled).

This function was introduced in Qt 5.5.

See also setComparisonMode().

bool QOpenGLTexture::create()

Creates the underlying OpenGL texture object. This requires a current valid OpenGL context. If the texture object already exists, this function does nothing.

Once the texture object is created you can obtain the object name from the textureId() function. This may be useful if you wish to make some raw OpenGL calls related to this texture.

Normally it should not be necessary to call this function directly as all functions that set properties of the texture object implicitly call create() on your behalf.

Returns true if the creation succeeded, otherwise returns false.

See also destroy(), isCreated(), and textureId().

QOpenGLTexture *QOpenGLTexture::createTextureView(Target target, TextureFormat viewFormat, int minimumMipmapLevel, int maximumMipmapLevel, int minimumLayer, int maximumLayer) const

Attempts to create a texture view onto this texture. A texture view is somewhat analogous to a view in SQL in that it presents a restricted or reinterpreted view of the original data. Texture views do not allocate any more server-side storage, insted relying on the storage buffer of the source texture.

Texture views are only available when using immutable storage. For more information on texture views see http://www.opengl.org/wiki/Texture_Storage#Texture_views.

The target argument specifies the target to use for the view. Only some targets can be used depending upon the target of the original target. For e.g. a view onto a Target1DArray texture can specify either Target1DArray or Target1D but for the latter the number of array layers specified with minimumLayer and maximumLayer must be exactly 1.

Simpliar constraints apply for the viewFormat. See the above link and the specification for more details.

The minimumMipmapLevel, maximumMipmapLevel, minimumLayer, and maximumLayer arguments serve to restrict the parts of the texture accessible by the texture view.

If creation of the texture view fails this function will return 0. If the function succeeds it will return a pointer to a new QOpenGLTexture object that will return true from its isTextureView() function.

See also isTextureView().

int QOpenGLTexture::depth() const

Returns the depth of a 3D texture.

See also width(), height(), and setSize().

DepthStencilMode QOpenGLTexture::depthStencilMode() const

Returns the depth stencil mode for textures using a combined depth/stencil format.

This function was introduced in Qt 5.4.

See also setDepthStencilMode().

void QOpenGLTexture::destroy()

Destroys the underlying OpenGL texture object. This requires a current valid OpenGL context.

See also create(), isCreated(), and textureId().

int QOpenGLTexture::faces() const

Returns the number of faces for this texture. For cubemap and cubemap array type targets this will be 6.

For non-cubemap type targets this will return 1.

TextureFormat QOpenGLTexture::format() const

Returns the format of this texture object.

See also setFormat().

void QOpenGLTexture::generateMipMaps()

Generates mipmaps for this texture object from mipmap level 0. If you are using a texture target and filtering option that requires mipmaps and you have disabled automatic mipmap generation then you need to call this function or the overload to create the mipmap chain.

Note: Mipmap generation is not supported for compressed textures with OpenGL ES 2.0.

See also setAutoMipMapGenerationEnabled(), setMipLevels(), and mipLevels().

void QOpenGLTexture::generateMipMaps(int baseLevel, bool resetBaseLevel = true)

Generates mipmaps for this texture object from mipmap level baseLevel. If you are using a texture target and filtering option that requires mipmaps and you have disabled automatic mipmap generation then you need to call this function or the overload to create the mipmap chain.

The generation of mipmaps to above baseLevel is achieved by setting the mipmap base level to baseLevel and then generating the mipmap chain. If resetBaseLevel is true, then the baseLevel of the texture will be reset to its previous value.

See also setAutoMipMapGenerationEnabled(), setMipLevels(), and mipLevels().

[static] bool QOpenGLTexture::hasFeature(Feature feature)

Returns true if your OpenGL implementation and version supports the texture feature feature.

int QOpenGLTexture::height() const

Returns the height of a 2D or 3D texture.

See also width(), depth(), and setSize().

bool QOpenGLTexture::isAutoMipMapGenerationEnabled() const

Returns whether auto mipmap generation is enabled for this texture object.

See also setAutoMipMapGenerationEnabled() and generateMipMaps().

bool QOpenGLTexture::isBound() const

Returns true if this texture is bound to the corresponding target of the currently active texture unit.

See also bind() and release().

bool QOpenGLTexture::isBound(uint unit)

Returns true if this texture is bound to the corresponding target of texture unit unit.

See also bind() and release().

bool QOpenGLTexture::isCreated() const

Returns true if the underlying OpenGL texture object has been created.

See also create(), destroy(), and textureId().

bool QOpenGLTexture::isFixedSamplePositions() const

Returns whether this texture uses a fixed pattern of multisample samples. If storage has not yet been allocated for this texture then this function returns the requested fixed sample position setting.

For texture targets that do not support multisampling this will return true.

See also setFixedSamplePositions() and isStorageAllocated().

bool QOpenGLTexture::isStorageAllocated() const

Returns true if server-side storage for this texture as been allocated.

The texture format, dimensions, mipmap levels and array layers cannot be altered once storage ihas been allocated.

See also allocateStorage(), setSize(), setMipLevels(), setLayers(), and setFormat().

bool QOpenGLTexture::isTextureView() const

Returns true if this texture object is actually a view onto another texture object.

See also createTextureView().

int QOpenGLTexture::layers() const

Returns the number of array layers for this texture. If storage has not yet been allocated for this texture then this function returns the requested number of array layers.

For texture targets that do not support array layers this will return 1.

See also setLayers() and isStorageAllocated().

QPair<float, float> QOpenGLTexture::levelOfDetailRange() const

Returns the minimum and maximum level of detail parameters.

See also setLevelOfDetailRange(), minimumLevelOfDetail(), and maximumLevelOfDetail().

float QOpenGLTexture::levelofDetailBias() const

Returns the level of detail bias parameter.

See also setLevelofDetailBias().

Filter QOpenGLTexture::magnificationFilter() const

Returns the magnification filter.

See also setMagnificationFilter().

float QOpenGLTexture::maximumAnisotropy() const

Returns the maximum level of anisotropy to be accounted for when performing texture lookups. This requires the GL_EXT_texture_filter_anisotropic extension.

See also setMaximumAnisotropy().

float QOpenGLTexture::maximumLevelOfDetail() const

Returns the maximum level of detail parameter.

See also setMaximumLevelOfDetail(), minimumLevelOfDetail(), and levelOfDetailRange().

int QOpenGLTexture::maximumMipLevels() const

Returns the maximum number of mipmap levels that this texture can have given the current dimensions.

See also setMipLevels(), mipLevels(), and setSize().

QPair<Filter, Filter> QOpenGLTexture::minMagFilters() const

Returns the current minification and magnification filters.

See also setMinMagFilters().

Filter QOpenGLTexture::minificationFilter() const

Returns the minification filter.

See also setMinificationFilter().

float QOpenGLTexture::minimumLevelOfDetail() const

Returns the minimum level of detail parameter.

See also setMinimumLevelOfDetail(), maximumLevelOfDetail(), and levelOfDetailRange().

int QOpenGLTexture::mipBaseLevel() const

Returns the mipmap base level used for all texture lookups with this texture. The default is 0.

See also setMipBaseLevel(), mipMaxLevel(), and mipLevelRange().

QPair<int, int> QOpenGLTexture::mipLevelRange() const

Returns the range of mipmap levels that can be used for texture lookups with this texture.

See also setMipLevelRange(), mipBaseLevel(), and mipMaxLevel().

int QOpenGLTexture::mipLevels() const

Returns the number of mipmap levels for this texture. If storage has not yet been allocated for this texture it returns the requested number of mipmap levels.

See also setMipLevels(), maximumMipLevels(), and isStorageAllocated().

int QOpenGLTexture::mipMaxLevel() const

Returns the mipmap maximum level used for all texture lookups with this texture.

See also setMipMaxLevel(), mipBaseLevel(), and mipLevelRange().

void QOpenGLTexture::release()

Unbinds this texture from the currently active texture unit.

See also bind().

void QOpenGLTexture::release(uint unit, TextureUnitReset reset = DontResetTextureUnit)

Unbinds this texture from texture unit unit.

If parameter reset is true then this function will restore the active unit to the texture unit that was active upon entry.

int QOpenGLTexture::samples() const

Returns the number of multisample sample points for this texture. If storage has not yet been allocated for this texture then this function returns the requested number of samples.

For texture targets that do not support multisampling this will return 0.

See also setSamples() and isStorageAllocated().

void QOpenGLTexture::setAutoMipMapGenerationEnabled(bool enabled)

If enabled is true, enables automatic mipmap generation for this texture object to occur whenever the level 0 mipmap data is set via setData().

The automatic mipmap generation is enabled by default.

Note: Mipmap generation is not supported for compressed textures with OpenGL ES 2.0.

See also isAutoMipMapGenerationEnabled() and generateMipMaps().

void QOpenGLTexture::setBorderColor(QColor color)

Sets the border color of the texture to color.

Note: This function has no effect on Mac and Qt built for OpenGL ES 2.

See also borderColor().

void QOpenGLTexture::setBorderColor(float r, float g, float b, float a)

Sets the color red to r, green to g, blue to b, and a to the alpha value.

This is an overloaded function.

void QOpenGLTexture::setBorderColor(int r, int g, int b, int a)

Sets the color red to r, green to g, blue to b, and the alpha value to a.

This is an overloaded function.

void QOpenGLTexture::setBorderColor(uint r, uint g, uint b, uint a)

Sets the color red to r, green to g, blue to b, and the alpha value to a.

This is an overloaded function.

void QOpenGLTexture::setComparisonFunction(ComparisonFunction function)

See also comparisonFunction().

void QOpenGLTexture::setComparisonMode(ComparisonMode mode)

Sets the texture comparison mode on this texture to mode. The texture comparison mode is used by shadow samplers when sampling a depth texture.

This function was introduced in Qt 5.5.

See also comparisonMode().

void QOpenGLTexture::setCompressedData(int mipLevel, int layer, CubeMapFace cubeFace, int dataSize, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

Uploads compressed pixel data to mipLevel, array layer, and cubeFace. The pixel transfer can optionally be controlled with options. The dataSize argument should specify the size of the data pointed to by data.

If not using a compressed format() then you should use setData() instead of this function.

This function was introduced in Qt 5.3.

void QOpenGLTexture::setCompressedData(int mipLevel, int layer, int dataSize, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

void QOpenGLTexture::setCompressedData(int mipLevel, int dataSize, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

void QOpenGLTexture::setCompressedData(int dataSize, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

void QOpenGLTexture::setData(int mipLevel, int layer, CubeMapFace cubeFace, PixelFormat sourceFormat, PixelType sourceType, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

Uploads pixel data for this texture object mipLevel, array layer, and cubeFace. Storage must have been allocated before uploading pixel data. Some overloads of setData() will set appropriate dimensions, mipmap levels, and array layers and then allocate storage for you if they have enough information to do so. This will be noted in the function documentation.

The structure of the pixel data pointed to by data is specified by sourceFormat and sourceType. The pixel data upload can optionally be controlled by options.

If using a compressed format() then you should use setCompressedData() instead of this function.

This function was introduced in Qt 5.3.

See also setCompressedData().

void QOpenGLTexture::setData(int mipLevel, int layer, PixelFormat sourceFormat, PixelType sourceType, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

This function was introduced in Qt 5.3.

void QOpenGLTexture::setData(int mipLevel, PixelFormat sourceFormat, PixelType sourceType, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

This function was introduced in Qt 5.3.

void QOpenGLTexture::setData(PixelFormat sourceFormat, PixelType sourceType, const void *data, const QOpenGLPixelTransferOptions * const options = Q_NULLPTR)

This is an overloaded function.

This function was introduced in Qt 5.3.

void QOpenGLTexture::setData(const QImage &image, MipMapGeneration genMipMaps = GenerateMipMaps)

This overload of setData() will allocate storage for you. The pixel data is contained in image. Mipmaps are generated by default. Set genMipMaps to DontGenerateMipMaps to turn off mipmap generation.

This is an overloaded function.

void QOpenGLTexture::setDepthStencilMode(DepthStencilMode mode)

If using a texture that has a combined depth/stencil format this function sets which component of the texture is accessed to mode.

When the parameter is set to DepthMode, then accessing it from the shader will access the depth component as a single float, as normal. But when the parameter is set to StencilMode, the shader will access the stencil component.

Note: This function has no effect on Mac and Qt built for OpenGL ES 2.

This function was introduced in Qt 5.4.

See also depthStencilMode().

void QOpenGLTexture::setFixedSamplePositions(bool fixed)

Sets whether the sample positions and number of samples used with a multisample capable texture target to fixed. If set to true the sample positions and number of samples used are the same for all texels in the image and will not depend upon the image size or internal format. This function should be called before storage is allocated for the texture.

For targets that do not support multisampling this function has no effect.

The default value is true.

See also isFixedSamplePositions() and isStorageAllocated().

void QOpenGLTexture::setFormat(TextureFormat format)

Sets the format of this texture object to format. This function must be called before texture storage is allocated.

Note that all formats may not be supported. The exact set of supported formats is dependent upon your OpenGL implementation and version.

See also format() and allocateStorage().

void QOpenGLTexture::setLayers(int layers)

Sets the number of array layers to allocate storage for. This function should be called before storage is allocated for the texture.

For targets that do not support array layers this function has no effect.

See also layers() and isStorageAllocated().

void QOpenGLTexture::setLevelOfDetailRange(float min, float max)

Sets the minimum level of detail parameters to min and the maximum level to max.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also levelOfDetailRange(), setMinimumLevelOfDetail(), and setMaximumLevelOfDetail().

void QOpenGLTexture::setLevelofDetailBias(float bias)

Sets the level of detail bias to bias. Level of detail bias affects the point at which mipmapping levels change. Increasing values for level of detail bias makes the overall images blurrier or smoother. Decreasing values make the overall images sharper.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also levelofDetailBias().

void QOpenGLTexture::setMagnificationFilter(Filter filter)

Sets the magnification filter to filter.

See also magnificationFilter(), setMinificationFilter(), and setMinMagFilters().

void QOpenGLTexture::setMaximumAnisotropy(float anisotropy)

If your OpenGL implementation supports the GL_EXT_texture_filter_anisotropic extension this function sets the maximum anisotropy level to anisotropy.

See also maximumAnisotropy().

void QOpenGLTexture::setMaximumLevelOfDetail(float value)

Sets the maximum level of detail to value. This limits the selection of lowest resolution mipmap (highest mipmap level). The default value is 1000.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also maximumLevelOfDetail(), setMinimumLevelOfDetail(), and setLevelOfDetailRange().

void QOpenGLTexture::setMinMagFilters(Filter minificationFilter, Filter magnificationFilter)

Sets the minification filter to minificationFilter and the magnification filter to magnificationFilter.

See also minMagFilters(), setMinificationFilter(), and setMagnificationFilter().

void QOpenGLTexture::setMinificationFilter(Filter filter)

Sets the filter used for minification to filter.

See also minificationFilter(), setMagnificationFilter(), and setMinMagFilters().

void QOpenGLTexture::setMinimumLevelOfDetail(float value)

Sets the minimum level of detail to value. This limits the selection of highest resolution mipmap (lowest mipmap level). The default value is -1000.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also minimumLevelOfDetail(), setMaximumLevelOfDetail(), and setLevelOfDetailRange().

void QOpenGLTexture::setMipBaseLevel(int baseLevel)

Sets the base mipmap level used for all texture lookups with this texture to baseLevel.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also mipBaseLevel(), setMipMaxLevel(), and setMipLevelRange().

void QOpenGLTexture::setMipLevelRange(int baseLevel, int maxLevel)

Sets the range of mipmap levels that can be used for texture lookups with this texture to range from baseLevel to maxLevel.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also setMipBaseLevel(), setMipMaxLevel(), and mipLevelRange().

void QOpenGLTexture::setMipLevels(int levels)

For texture targets that support mipmaps, this function sets the requested number of mipmap levels to allocate storage for. This function should be called before storage is allocated for the texture.

If the texture target does not support mipmaps this function has no effect.

See also mipLevels(), maximumMipLevels(), and isStorageAllocated().

void QOpenGLTexture::setMipMaxLevel(int maxLevel)

Sets the maximum mipmap level used for all texture lookups with this texture to maxLevel.

Note: This function has no effect on Qt built for OpenGL ES 2.

See also mipMaxLevel(), setMipBaseLevel(), and setMipLevelRange().

void QOpenGLTexture::setSamples(int samples)

Sets the number of samples to allocate storage for when rendering to a multisample capable texture target. This function should be called before storage is allocated for the texture.

For targets that do not support multisampling this function has no effect.

See also samples() and isStorageAllocated().

void QOpenGLTexture::setSize(int width, int height = 1, int depth = 1)

Sets the dimensions of this texture object to width, height, and depth. The default for each dimension is 1. The maximum allowable texture size is dependent upon your OpenGL implementation. Allocating storage for a texture less than the maximum size can still fail if your system is low on resources.

See also width(), height(), and depth().

void QOpenGLTexture::setSwizzleMask(SwizzleComponent component, SwizzleValue value)

GLSL shaders are able to reorder the components of the vec4 returned by texture functions. It is also desirable to be able to control this reordering from CPU side code. This is made possible by swizzle masks since OpenGL 3.3.

Each component of the texture can be mapped to one of the SwizzleValue options.

This function maps component to the output value.

Note: This function has no effect on Mac and Qt built for OpenGL ES 2.

See also swizzleMask().

void QOpenGLTexture::setSwizzleMask(SwizzleValue r, SwizzleValue g, SwizzleValue b, SwizzleValue a)

Parameters r, g, b, and a are values used for setting the colors red, green, blue, and the alpha value.

This is an overloaded function.

void QOpenGLTexture::setWrapMode(WrapMode mode)

Sets the wrap (or repeat mode) for all texture dimentions to mode.

See also wrapMode().

void QOpenGLTexture::setWrapMode(CoordinateDirection direction, WrapMode mode)

Holds the texture dimension direction.

This is an overloaded function.

SwizzleValue QOpenGLTexture::swizzleMask(SwizzleComponent component) const

Returns the swizzle mask for texture component.

See also setSwizzleMask().

Target QOpenGLTexture::target() const

Returns the binding target of this texture.

This function was introduced in Qt 5.4.

GLuint QOpenGLTexture::textureId() const

Returns the name of the underlying OpenGL texture object or 0 if it has not yet been created.

See also create(), destroy(), and isCreated().

int QOpenGLTexture::width() const

Returns the width of a 1D, 2D or 3D texture.

See also height(), depth(), and setSize().

WrapMode QOpenGLTexture::wrapMode(CoordinateDirection direction) const

Returns the wrap mode for the texture dimension direction.

See also setWrapMode().