Detailed Description
The QGLMaterialCollection class manages groups of materials.
Managing more complex 3d graphics with several materials is easier when the materials can be referred to as a collection. This is the role of the QGLMaterialCollection class.
Plug-ins implementing 3D formats may make the materials defined in the format available to the application via a QGLMaterialCollection.
The collection is also optimised for the case where many small objects must refer to materials - such as faces in a mesh, or particles. In this case the materials can be specified as a short data type using an offset into the collection, rather than the material name.
When building up a collection, meshes that refer to the various materials can check off which ones are used by calling markMaterialAsUsed(), and then remove spurious unused materials by calling removeUnusedMaterials(). This technique is suitable for models loaded from a model file where a large number of materials may be specified but only a few of those materials are used by the particular mesh selected from the scene.
To make a material available from a collection, call addMaterial(). To retrieve a material from the collection call removeMaterial().
The collection takes ownership of the QGLMaterial objects passed to it by the addMaterial() function. These objects will be destroyed when the collection is destroyed.
Member Function Documentation
QGLMaterialCollection::QGLMaterialCollection(QObject * parent = 0)
Construct a new empty QGLMaterialCollection object. The parent is set as the parent of this object.
QGLMaterialCollection::~QGLMaterialCollection() [virtual]
Destroy this collection. All material objects referred to by this collection will be destroyed.
int QGLMaterialCollection::addMaterial(QGLMaterial * material)
Adds material to this collection and returns its new index. The collection takes ownership of the material and will delete it when the collection is destroyed. Initially the material is marked as unused.
The QObject::objectName() of material at the time addMaterial() is called will be used as the material's name within this collection. Changes to the object name after the material is added are ignored.
If material is already present in this collection, then this function will return the index that was previously assigned.
Returns -1 if material has been added to another collection.
See also removeMaterial() and markMaterialAsUsed().
bool QGLMaterialCollection::contains(QGLMaterial * material) const
Returns true if this collection contains material; false otherwise.
See also indexOf().
bool QGLMaterialCollection::contains(const QString & name) const
This is an overloaded function.
Returns true if this collection contains a material called name; false otherwise.
See also indexOf().
int QGLMaterialCollection::indexOf(QGLMaterial * material) const
Returns the index of material in this collection; -1 if material is not present in this collection.
See also contains().
int QGLMaterialCollection::indexOf(const QString & name) const
This is an overloaded function.
Returns the index of the material called name in this collection; -1 if name is not present in this collection.
See also contains().
bool QGLMaterialCollection::isEmpty() const
Returns true if this collection is empty, false otherwise.
See also size().
bool QGLMaterialCollection::isMaterialUsed(int index) const
Returns true if the material at index in this collection has been marked as used by markMaterialAsUsed().
See also markMaterialAsUsed().
void QGLMaterialCollection::markMaterialAsUsed(int index)
Flags the material corresponding to the index as used. Some model files may contain a range of materials, applying to various objects in the scene.
When a particular object is loaded from the file, many of those materials may not be used in that object. This wastes space, with many spurious materials being stored.
Use this method during model loading or construction to mark off materials that have been used. Materials so marked will not be removed by removeUnusedMaterials().
See also removeUnusedMaterials() and isMaterialUsed().
QGLMaterial * QGLMaterialCollection::material(int index) const
Returns a pointer to the material corresponding to index; or null if index is out of range or the material has been removed.
Here's an example of searching for a material with a given ambient color in the collection materials:
for (int colorIndex; colorIndex < materials->size(); ++colorIndex) {
if (material(colorIndex) &&
material(colorIndex)->ambientColor() == color)
break;
}
if (colorIndex < materials->size())
myObject->setMaterial(colorIndex);
QGLMaterial * QGLMaterialCollection::material(const QString & name) const
This is an overloaded function.
Returns the material associated with name in this collection; null if name is not present or the material has been removed.
QString QGLMaterialCollection::materialName(int index) const
Returns the name of the material at index in this material collection; a null QString if index is out of range.
void QGLMaterialCollection::removeMaterial(QGLMaterial * material)
Removes all instances of material from this collection. The material object is not deleted and can be reused.
Does nothing if material is null or not a member of this collection.
See also addMaterial().
QGLMaterial * QGLMaterialCollection::removeMaterial(int index)
Removes the material at index from this collection, and returns a pointer to the material.
Since the collection is designed for fast lookup by index, the the stored material pointer is set to null but the index otherwise remains valid.
void QGLMaterialCollection::removeUnusedMaterials()
Removes and deletes materials which have not been marked as used.
See also markMaterialAsUsed() and isMaterialUsed().
int QGLMaterialCollection::size() const
Returns the number of (possibly null) materials in this collection. Null materials result from calling removeMaterial().
See also isEmpty().
