Detailed Description
The QGLTexture2D class represents a 2D texture object for GL painting operations.
QGLTexture2D contains a QImage and settings for texture filters, wrap modes, and mipmap generation. When bind() is called, this information is uploaded to the GL server if it has changed since the last time bind() was called.
To enable a texture so that it will be used in the next draw call, use bind(). To disable the texture so that it will no longer be used in drawing call release(). To remove the texture from the GL server altogether call cleanupResources().
Once a QGLTexture2D object is created, it can be bound to multiple GL contexts. Internally, a separate texture identifier is created for each context. This makes QGLTexture2D easier to use than raw GL texture identifiers because the application does not need to be as concerned with whether the texture identifier is valid in the current context. The application merely calls bind() and QGLTexture2D will create a new texture identifier for the context if necessary. When cleanupResources() is called the texture will be removed from the GL server, and will no longer be available to any of the multiple contexts.
QGLTexture2D internally points to a reference-counted object that represents the current texture state. If the QGLTexture2D is copied, the internal pointer is the same. Modifications to one QGLTexture2D copy will affect all of the other copies in the system.
When the QGLTexture2D object is deleted, no attempt is made to remove the texture resources from the GL server. The application programmer must call cleanupResources(). The reason is that the relevant GL context must be current (or be made current) for GL resources to be removed, but the context is likely to be in a different thread.
The application programmer thus has control over the life-cycle of the GL resources, and has the option to keep the QGLTexture2D object around with its attached image in heap memory; whilst not consuming resources on the GPU. This is useful in larger scenes, or when used with LOD and higher-level culling.
QGLTexture2D can also be used for uploading 1D textures into the GL server by specifying an image() with a height of 1.
Member Function Documentation
QGLTexture2D::QGLTexture2D(QObject * parent = 0)
Constructs a null texture object and attaches it to parent.
See also isNull().
QGLTexture2D::~QGLTexture2D()
Destroys this texture object. Call cleanupResources() before destroying the object in order to remove GL resources from the server - this is not done automatically, as destruction is not guaranteed to occur in the same thread as the context.
bool QGLTexture2D::bind() const
Binds this texture to the 2D texture target.
If this texture object is not associated with an identifier in the current context, then a new identifier will be created, and image() uploaded into the GL server.
To remove the resources from the GL server when this texture is no longer required, call cleanupResources().
If setImage(), setSize() or setBindOptions() were called since the last upload, then image() will be re-uploaded to the GL server, except for the special case where setBindOptions() changed only the LinearFilteringBindOption.
Returns false if the texture could not be bound for some reason.
See also release(), textureId(), and setImage().
BindOptions QGLTexture2D::bindOptions() const
Returns the options to use when binding the image() to an OpenGL context for the first time. The default options are QGLTexture2D::LinearFilteringBindOption | QGLTexture2D::InvertedYBindOption | QGLTexture2D::MipmapBindOption.
See also setBindOptions().
bool QGLTexture2D::cleanupResources()
Cleans up the resources associated with the QGLTexture2D.
Calling this function to clean up resources must be done manually within the users' code. Cleanup should be undertaken on application close, or when the QOpenGLContext associated with these resources is otherwise being destroyed.
The user must ensure that the current thread in "owns" the associated QOpenGLContext, and that this context has been made current prior to cleanup. If these conditions are satisfied the user may simply call the cleanupResources() function.
In multi-threaded applications where the user cannot ensure the context exists in the current thread, or that the context can be made current, the relevant context is generally available from within paint function, so the cleanupResources function should be called at the start of painting. An example of an application where scenario arises is in multi-threaded QML2 application which uses a separate thread for rendering.
If the context is not current or available the function will generate a warning and fail to cleanup the resources associated with that context.
This does not remove any client side image that may be stored: for that, see clearImage().
See also bind() and release().
void QGLTexture2D::clearImage()
Clears the image() that is associated with this texture, but the GL texture will retain its current value. This can be used to release client-side memory that is no longer required once the image has been uploaded into the GL server.
The following code will queue image to be uploaded, immediately force it to be uploaded into the current GL context, and then clear the client copy:
texture.setImage(image);
texture.bind();
texture.clearImage()
See also image() and setImage().
QGLTexture2D * QGLTexture2D::fromTextureId(GLuint id, const QSize & size) [static]
Constructs a QGLTexture2D object that wraps the supplied literal texture identifier id, with the dimensions specified by size.
The id is assumed to have been created by the application in the current GL context, and it will be destroyed by the application after the returned QGLTexture2D object is destroyed.
This function is intended for interfacing to existing code that uses raw GL texture identifiers. The returned QGLTexture2D can only be used with the current GL context.
See also textureId().
bool QGLTexture2D::hasAlphaChannel() const
Returns true if this texture has an alpha channel; false if the texture is fully opaque.
QGL::TextureWrap QGLTexture2D::horizontalWrap() const
Returns the wrapping mode for horizontal texture co-ordinates. The default value is QGL::Repeat.
See also setHorizontalWrap() and verticalWrap().
QImage QGLTexture2D::image() const
Returns the image that is currently associated with this texture. The image may not have been uploaded into the GL server yet. Uploads occur upon the next call to bind().
See also setImage().
bool QGLTexture2D::isNull() const
Returns true if this texture object is null; that is, image() is null and textureId() is zero.
void QGLTexture2D::release() const
Releases the texture associated with the 2D texture target. This is equivalent to glBindTexture(GL_TEXTURE_2D, 0).
See also bind().
QSize QGLTexture2D::requestedSize() const
Returns the size that was previously set with setSize() before it was rounded to a power of two.
See also size() and setSize().
void QGLTexture2D::setBindOptions(BindOptions options)
Sets the options to use when binding the image() to an OpenGL context. If the image() has already been bound, then changing the options will cause it to be recreated from image() the next time bind() is called, unless the only change was to the LinearFilteringBindOption, which can be applied without re-creation.
See also bindOptions() and bind().
bool QGLTexture2D::setCompressedFile(const QString & path)
Sets this texture to the contents of a compressed image file at path. Returns true if the file exists and has a supported compressed format; false otherwise.
The DDS, ETC1, PVRTC2, and PVRTC4 compression formats are supported, assuming that the GL implementation has the appropriate extension.
See also setImage() and setSize().
void QGLTexture2D::setHorizontalWrap(QGL::TextureWrap value)
Sets the wrapping mode for horizontal texture co-ordinates to value.
The value will not be applied to the texture in the GL server until the next call to bind().
See also horizontalWrap() and setVerticalWrap().
void QGLTexture2D::setImage(const QImage & image)
Sets the image that is associated with this texture. The image will be uploaded into the GL server the next time bind() is called.
If setSize() or setImage() has been called previously, then image will be scaled to size() when it is uploaded.
If image is null, then this function is equivalent to clearImage().
See also image(), setSize(), and setPixmap().
void QGLTexture2D::setPixmap(const QPixmap & pixmap)
Sets the image that is associated with this texture to pixmap.
This is a convenience that calls setImage() after converting pixmap into a QImage. It may be more efficient on some platforms than the application calling QPixmap::toImage().
See also setImage().
void QGLTexture2D::setSize(const QSize & value)
Sets the size of this texture to value. Also sets the requestedSize to value.
Note that the underlying OpenGL implementation may require texture sizes to be a power of two. If that is the case, then when the texture is bound this will be detected, and while requestedSize() will remain at value, the size() will be set to the next power of two equal to or greater than value.
For this reason to get a definitive value of the actual size of the underlying texture, query the size after bind() has been done.
See also size() and requestedSize().
void QGLTexture2D::setUrl(const QUrl & url)
Sets this texture to have the contents of the image stored at url.
See also url().
void QGLTexture2D::setVerticalWrap(QGL::TextureWrap value)
Sets the wrapping mode for vertical texture co-ordinates to value.
If value is not supported by the OpenGL implementation, it will be replaced with a value that is supported. If the application desires a very specific value, it can call verticalWrap() to check that the specific value was actually set.
The value will not be applied to the texture in the GL server until the next call to bind().
See also verticalWrap() and setHorizontalWrap().
QSize QGLTexture2D::size() const
Returns the size of this texture. If the underlying OpenGL implementation requires texture sizes to be a power of two, then this function may return the next power of two equal to or greater than requestedSize()
The adjustment to the next power of two will only occur when an OpenGL context is available, so if the actual texture size is needed call this function when a context is available.
See also setSize() and requestedSize().
GLuint QGLTexture2D::textureId() const
Returns the identifier associated with this texture object in the current context.
Returns zero if the texture has not previously been bound to the 2D texture target in the current context with bind().
See also bind().
void QGLTexture2D::textureRequestFinished(QByteArray * assetData) [slot]
This slot is used to recieve signals from the QDownloadManager class which provides Url download capability across the network.
A successful download will have a valid QByteArray stored in assetData, while a failed download (due to network error, etc), will result in a NULL value.
Successful downloads use the image data downloaded into assetData, which is converted to an image/texture, and emit a textureUpdated() signal.
See also QDownloadManager.
void QGLTexture2D::textureUpdated() [signal]
Signals that some property of this texture has changed in a manner that may require that the parent material class be updated.
QUrl QGLTexture2D::url() const
Returns the url that was last set with setUrl.
See also setUrl().
QGL::TextureWrap QGLTexture2D::verticalWrap() const
Returns the wrapping mode for vertical texture co-ordinates. The default value is QGL::Repeat.
See also setVerticalWrap() and horizontalWrap().
