QGLTextureCube Class

Member Function Documentation

QGLTextureCube::QGLTextureCube()

Constructs a null texture object.

See also isNull().

QGLTextureCube::~QGLTextureCube()

Destroys this texture object. If this object is the last reference to the underlying GL texture, then the underlying GL texture will also be deleted.

bool QGLTextureCube::bind() const

Binds this texture to the cube map texture target.

If this texture object is not associated with an identifier in the current context, then a new identifier will be created, and the face images will be uploaded into the GL server.

If setImage() or setSize() was called since the last upload, then the face images will be re-uploaded to the GL server.

Returns false if the texture could not be bound for some reason.

See also release(), textureId(), and setImage().

QGLTexture2D::BindOptions QGLTextureCube::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 QGLTextureCube::cleanupResources()

Cleans up the resources associated with the QGLTextureCube.

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.

See also bind() and release().

void QGLTextureCube::clearImage(QGLTextureCube::Face face)

Clears the image() that is associated with this texture on the specified face of the cube map. 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 as the positive X face of the cube map, immediately force it to be uploaded into the current GL context, and then clear the client copy:

 texture.setImage(QGLTextureCube::PositiveX, image);
 texture.bind();
 texture.clearImage(QGLTextureCube::PositiveX);

See also image() and setImage().

QGLTextureCube * QGLTextureCube::fromTextureId(GLuint id, const QSize & size) [static]

Constructs a QGLTextureCube 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 QGLTextureCube object is destroyed.

This function is intended for interfacing to existing code that uses raw GL texture identifiers. The returned QGLTextureCube can only be used with the current GL context.

See also textureId().

bool QGLTextureCube::hasAlphaChannel() const

Returns true if this texture has an alpha channel; false if the texture is fully opaque.

QGL::TextureWrap QGLTextureCube::horizontalWrap() const

Returns the wrapping mode for horizontal texture co-ordinates. The default value is QGL::Repeat.

See also setHorizontalWrap() and verticalWrap().

QImage QGLTextureCube::image(QGLTextureCube::Face face) const

Returns the image that is currently associated with the specified face of this cube map 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 QGLTextureCube::isNull() const

Returns true if this texture object is null; that is, all image() values are null and textureId() is zero.

void QGLTextureCube::release() [static]

Releases the texture associated with the cube map texture target. This is equivalent to glBindTexture(GL_TEXTURE_CUBE_MAP, 0).

See also bind().

QSize QGLTextureCube::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 QGLTextureCube::setBindOptions(QGLTexture2D::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.

See also bindOptions() and bind().

void QGLTextureCube::setHorizontalWrap(QGL::TextureWrap value)

Sets the wrapping mode for horizontal 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 horizontalWrap() 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 horizontalWrap() and setVerticalWrap().

void QGLTextureCube::setImage(QGLTextureCube::Face face, const QImage & image)

Sets the image that is associated with this texture on the specified face of the cube map. 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() and setSize().

void QGLTextureCube::setSize(const QSize & value)

Sets the size of this texture to value. If the underlying OpenGL implementation requires texture sizes to be a power of two, then requestedSize() will be set to value, and the actual size will be set to the next power of two equal to or greater than value. Otherwise both size() and requestedSize() will be set to value.

See also size() and requestedSize().

void QGLTextureCube::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 QGLTextureCube::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 will return the next power of two equal to or greater than requestedSize()

See also setSize() and requestedSize().

GLuint QGLTextureCube::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().

QGL::TextureWrap QGLTextureCube::verticalWrap() const

Returns the wrapping mode for vertical texture co-ordinates. The default value is QGL::Repeat.

See also setVerticalWrap() and horizontalWrap().