The material managing static class. More...

#include <VR3MaterialManager.h>

Classes
struct	MapElement
	An element in the mesh map. More...
Static Public Member Functions
Material Discovery Function
static int	ListMaterialsAAM (const char *file_name, int ids[], std::string mat_names[], int subids[], std::string multimat_names[], int count)
	Lists the names and the ids of the meshes available in a given file.
Private Member Functions
	VR3MaterialManager ()
	Private constructor to avoid explicit instantiation.
Static Private Attributes
static std::map< std::string, std::map< int, std::map< int, MapElement > >, VR3Map::Less >	ms_materials
	Mapping of material file names and material IDs to material object references.
Material Loading Functions
static void	LoadMatTextureAAM (std::ifstream &is, const char file_name, VR3Material::MatTexture mattex)
	Loads a new texture from an AAM file.
static void	LoadMatAAM (const char file_name, VR3Material material, const char mat_name=0, int matID=-1, const char multimat_name=0, int submatID=-1)
	Loads a new material from an AAM file.
Material Management Functions
static void	CreateMaterial (VR3Material *material)
	Notifies the creation of a new material.
static VR3Material *	FindMaterial (const char file_name, const char mat_name=0, int matID=-1, const char *multimat_name=0, int submatID=-1)
	Searches the current material pool for the provided material clues.
static void	DeleteReference (VR3Material *material)
	Notifies the deletion of a reference to a material.
static void	AddReference (VR3Material *material)
	Notifies that a reference has been instantiated.

Detailed Description

The material managing static class.

This class can be viewed as a namespace with private data members, it cannot be instantiated explicitly and should only be used through the static material loading methods.

The VR3MaterialManager class works as the material manager class, notice that 2 entities may have references to material objects:

The user (explicitly calling the VR3Material constructor),
meshes building their mesh object or receiving a pre-built one.

This manager class is used to ensure that duplicated material objects representing the same material are never created.

This class also provides the material loading functions, so it is the material loader and manager class.

Materials recovered from files may either be simple materials, or multimaterials (collection of simple materials). The entity represented by a VR3Material object is always a simple material. A group of VR3Material objects may therefore represent a multimaterial. Materials inside multimaterials may be also replicated in other multimaterials or as simple materials at global level, in this case the material data is effectively replicated when all those materials are loaded.

Definition at line 56 of file VR3MaterialManager.h.

Constructor & Destructor Documentation

VR3MaterialManager::VR3MaterialManager ( ) [private]

Private constructor to avoid explicit instantiation.

Member Function Documentation

static void VR3MaterialManager::AddReference ( VR3Material * material ) [static]

Notifies that a reference has been instantiated.

This function is useful when the reference to a material is returned to the user asking it to a mesh, or when the material associated with a mesh is changed. The AddReference function simply increments the reference counter associated to a particular VR3Material object.

Parameters:

[in] material The material object

static void VR3MaterialManager::CreateMaterial ( VR3Material * material ) [static, private]

Notifies the creation of a new material.

When a new material is created, this function is called inside the material loading function to notify the VR3MaterialManager that a new material is being created. An error arises if a material with the same file name and material ID already exists. This function is called from the VR3MaterialManager::LoadMatAAM() function.

Parameters:

[in] material A reference to the new material object

static void VR3MaterialManager::DeleteReference ( VR3Material * material ) [static]

Notifies the deletion of a reference to a material.

A material may only be deleted by this material loading and managing module, when a mesh linked to some material terminates its life time, it simply calls the pseudo-destructor VR3Material::Destroy(). The VR3Material::Destroy() method will simply notify the material manager that a reference to the specified material has been deleted.

Parameters:

[in] material The material object

static VR3Material* VR3MaterialManager::FindMaterial	(	const char *	file_name,
		const char *	mat_name = `0`,
		int	matID = `-1`,
		const char *	multimat_name = `0`,
		int	submatID = `-1`
	)		`[static]`

Searches the current material pool for the provided material clues.

This function is used to avoid multiple instantiations of the same material. A mesh pool is mantained and continuously updated stating which VR3Material object is associated to which (file,objID) couple. This function is used to avoid material instantiation if possible. The mat_name and matID are used to specify the particular material object to search for, they may be used together, singularly or none at all (in such case any material object from the file may be returned). A submaterial ID may be specified in case we are looking for a particular material inside a multimaterial.

Parameters:

[in]	file_name	The requested file name
[in]	mat_name	The requested material name in the file
[in]	matID	The requested material ID inside the file
[in]	multimat_name	The name of the material containing the desired one
[in]	submatID	The submaterial ID if the material is part of a multimaterial (use VR3MAT_NOSUB to specify a material not part of another material)

Returns:: The found material object or 0 if no matching material was found

static int VR3MaterialManager::ListMaterialsAAM	(	const char *	file_name,
		int	ids[],
		std::string	mat_names[],
		int	subids[],
		std::string	multimat_names[],
		int	count
	)		`[static]`

Lists the names and the ids of the meshes available in a given file.

Given a mesh file, this function may be used to retrieve the list of all available materials in the file. The name of the materials is returned together with their ID. As usual, a material is intended as an entity that can be loaded obtaining a VR3Material object. When the AAM file contains one or more multimaterials, a different entry for each available submaterial will be returned by the function stating also the containing multimaterial name and the ID of the material as a submaterial. If the ids parameter, the mat_names parameter, the subids parameter or the multimat_names parameter is set to 0 (NULL), the only use of the function is the discovery of the number of materials in the file: the names and the ids will not be returned. This function only works for AAM files.

Parameters:

[in]	file_name	The name of the file
[out]	ids	The retrieved ids of the materials (may be used to load them)
[out]	mat_names	The retrieved names of the materials (may be used to load them)
[out]	subids	The retrieved ids of the materials as submaterials (VR3MAT_NOSUB if not a submaterial)
[out]	multimat_names	The retrieved names of the containing multimaterial (empty string if not submaterial)
[in]	count	The number of elements available in the above arrays for writing

Returns:: The effective number of available materials in the file

static void VR3MaterialManager::LoadMatAAM	(	const char *	file_name,
		VR3Material *	material,
		const char *	mat_name = `0`,
		int	matID = `-1`,
		const char *	multimat_name = `0`,
		int	submatID = `-1`
	)		`[static]`

Loads a new material from an AAM file.

This function loads the material specification for our mesh, notice that the referenced material in the AAM file may be referenced by other objects in the same file; moreover, the same texture file may be required for different materials. When a material is loaded from an AAM file, the specified object ID and material name inside the file may determine which material to load. If no mat_name (material name in the AAM file), matID or submatID is specified, the first material encountered will be loaded. The submatID is only considered once the material has been identified using the other parameters (therefore if only the submatID is provided the function will likely fail because the first material encountered does not have a proper submaterial). Please note that the material name always refer to the simple material name, that is, the submaterial name in case of multimaterials.

Parameters:

[in]	file_name	Name of the AAM file
[out]	material	The material object to fill
[in]	mat_name	The material name inside the AAM file (0 if any)
[in]	matID	The material ID inside the AAM file (-1 if any)
[in]	multimat_name	The name of the material containing the desired one
[in]	submatID	The submaterial ID if the material is part of a multimaterial (use VR3MAT_NOSUB to specify to avoid loading a submaterial).

static void VR3MaterialManager::LoadMatTextureAAM	(	std::ifstream &	is,
		const char *	file_name,
		VR3Material::MatTexture *	mattex
	)		`[static, private]`

Loads a new texture from an AAM file.

This function loads the parameters of a texture applied to a specific material, that is tiling, rotation, etc... Notice that this function does not load the effective texture image (the real texture), but just the texture parameters as applied to the material.

Parameters:

[in]	is	The opened input stream to read the file
[in]	file_name	Name of the AAM file
[out]	mattex	The VR3Material::MatTexture object where to write the data.

Member Data Documentation

std::map<std::string,std::map<int,std::map<int,MapElement> >,VR3Map::Less> VR3MaterialManager::ms_materials [static, private]

Mapping of material file names and material IDs to material object references.

Definition at line 67 of file VR3MaterialManager.h.

The documentation for this class was generated from the following file:

include/VR3MaterialManager.h

VR3MaterialManager Class Reference

Classes

Static Public Member Functions

Private Member Functions

Static Private Attributes

Material Loading Functions

Material Management Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation