Detailed Description
The QGLAbstractMaterial class provides a standard interface for rendering surface materials with GL.
Materials are the primary method to specify the surface appearance of an object, as distinct from the geometry for the object. Materials have an almost endless variety of parameters:
- Properties of the material under various lighting conditions; i.e., the traditional parameters for ambient, diffuse, specular, etc.
- Textures in multiple layers, with different combination modes; decal, modulate, replace, etc.
- Environmental conditions such as fogging.
- Alpha values for opacity and blending.
- Interpolation factors for animated surface effects.
- etc
QGLAbstractMaterial is the base class for all such materials. It provides a very simple API to bind() a material to a QGLPainter when the material needs to be rendered, to release() a material from a QGLPainter when the material is no longer needed, and to prepareToDraw().
Subclasses of QGLAbstractMaterial implement specific materials. QGLMaterial provides the traditional ambient, diffuse, specular, etc parameters for lighting properties.
Materials are distinct from effects, which have the base class QGLAbstractEffect. Effects are typically shader programs that are used to render a specific type of material. The material's bind() function will use QGLPainter::setStandardEffect() or QGLPainter::setUserEffect() to select the exact effect that is needed to render the material.
It is possible that the same material may be rendered with different effects depending upon the material parameters. For example, a lit material may select a simpler and more efficient shader program effect if the material has the default spotlight properties, or if the QGLPainter only has a single light source specified.
Member Function Documentation
QGLAbstractMaterial::QGLAbstractMaterial(QObject * parent = 0)
Constructs a new material and attaches it to parent.
QGLAbstractMaterial::~QGLAbstractMaterial()
Destroys this material.
QGLMaterial * QGLAbstractMaterial::back() const [virtual]
Returns the material lighting parameters for rendering the back faces of fragments with this abstract material. The default implementation returns null, which indicates that front() is also used to render back faces.
See also front() and QGLMaterial.
void QGLAbstractMaterial::bind(QGLPainter * painter) [pure virtual]
Binds resources to painter that are needed to render this material; textures, shader programs, blending modes, etc.
In the following example, lit material parameters and a texture are bound to the painter, for rendering with the standard QGL::LitModulateTexture2D effect:
void TexturedLitMaterial::bind(QGLPainter *painter)
{
painter->setStandardEffect(QGL::LitModulateTexture2D);
painter->setFaceMaterial(QGL::AllFaces, material);
painter->glActiveTexture(GL_TEXTURE0);
texture->bind();
}
Normally the effect is bound to painter during the bind() function. However, some materials may need to use different effects depending upon which attributes are present in the geometry. For example, a per-vertex color effect instead of a uniform color effect if the geometry has the QGL::Color attribute. The prepareToDraw() function can be overridden to alter the effect once the specific set of geometry attributes are known.
See also release() and prepareToDraw().
QGLMaterial * QGLAbstractMaterial::front() const [virtual]
Returns the material lighting parameters for rendering the front faces of fragments with this abstract material. The default implementation returns null.
This function is provided as a convenience for applications that wish to alter the lighting parameters or textures of a material, without regard to any wrapping that has been performed to add blending or other options.
See also back() and QGLMaterial.
bool QGLAbstractMaterial::isTransparent() const [pure virtual]
Returns true if this material is transparent and will therefore require the GL_BLEND mode to be enabled to render the material. Returns false if the material is fully opaque.
void QGLAbstractMaterial::materialChanged() [signal]
Signal that is emitted when an object that is using this material should be redrawn because some property on the material has changed.
void QGLAbstractMaterial::prepareToDraw(QGLPainter * painter, const QGLAttributeSet & attributes) [virtual]
Prepares to draw geometry to painter that has the specified set of vertex attributes. The default implementation does nothing.
Multiple effects may be used to render some materials depending upon the available vertex attributes. For example, if QGL::Color is present in attributes, then a per-vertex color should be used instead of a single uniform color.
This function is provided for such materials to have one last chance during QGLPainter::draw() to alter the QGLPainter::effect() to something that is tuned for the specific geometry. It can be assumed that bind() has already been called on this material.
See also bind() and release().
void QGLAbstractMaterial::release(QGLPainter * painter, QGLAbstractMaterial * next) [pure virtual]
Releases resources from painter that were used to render this material. The QGLPainter::effect() can be left bound to painter, but other resources such as textures and blending modes should be disabled.
If next is not null, then it indicates the next material that will be bound to painter. If next is the same type of material as this material, then this function can choose not to release resources that would be immediately re-bound to painter in the next call to bind().
In the following example, texture unit 0 is unbound if painter is about to switch to another effect that is not an instance of TexturedLitMaterial:
void TexturedLitMaterial::release(QGLPainter *painter, QGLAbstractMaterial *next)
{
if (!qobject_cast<TexturedLitMaterial *>(next)) {
painter->glActiveTexture(GL_TEXTURE0);
glBindTexture(GL_TEXTURE_2D, 0);
}
}
See also bind() and prepareToDraw().
