Assimp  v4.1. (December 2018)
Assimp::MDLImporter Class Reference

Class to load MDL files. More...

Inherits Assimp::BaseImporter.

Inherited by Assimp::HMPImporter.

Public Member Functions

bool CanRead (const std::string &pFile, IOSystem *pIOHandler, bool checkSig) const
 Returns whether the class can handle the format of the given file. More...
 
 MDLImporter ()
 
void SetupProperties (const Importer *pImp)
 Called prior to ReadFile(). More...
 
 ~MDLImporter ()
 
- Public Member Functions inherited from Assimp::BaseImporter
 BaseImporter ()
 Constructor to be privately used by Importer. More...
 
const std::string & GetErrorText () const
 Returns the error description of the last error that occurred. More...
 
void GetExtensionList (std::set< std::string > &extensions)
 Called by #Importer::GetExtensionList for each loaded importer. More...
 
aiSceneReadFile (const Importer *pImp, const std::string &pFile, IOSystem *pIOHandler)
 Imports the given file and returns the imported data. More...
 
virtual ~BaseImporter ()
 Destructor, private as well. More...
 

Protected Member Functions

void AddAnimationBoneTrafoKey_3DGS_MDL7 (unsigned int iTrafo, const MDL::BoneTransform_MDL7 *pcBoneTransforms, MDL::IntBone_MDL7 **apcBonesOut)
 Add a bone transformation key to an animation. More...
 
void AddBonesToNodeGraph_3DGS_MDL7 (const MDL::IntBone_MDL7 **apcBonesOut, aiNode *pcParent, uint16_t iParentIndex)
 Add all bones to the nodegraph (as children of the root node) More...
 
void BuildOutputAnims_3DGS_MDL7 (const MDL::IntBone_MDL7 **apcBonesOut)
 Build output animations. More...
 
void CalcAbsBoneMatrices_3DGS_MDL7 (MDL::IntBone_MDL7 **apcOutBones)
 Calculate absolute bone animation matrices for each bone. More...
 
void CalculateUVCoordinates_MDL5 ()
 Converts the absolute texture coordinates in MDL5 files to relative in a range between 0 and 1. More...
 
void CopyMaterials_3DGS_MDL7 (MDL::IntSharedData_MDL7 &shared)
 Copies only the material that are referenced by at least one mesh to the final output material list. More...
 
void CreateTexture_3DGS_MDL4 (const unsigned char *szData, unsigned int iType, unsigned int *piSkip)
 Used to load textures from MDL3/4. More...
 
void CreateTexture_3DGS_MDL5 (const unsigned char *szData, unsigned int iType, unsigned int *piSkip)
 Used to load textures from MDL5. More...
 
void CreateTextureARGB8_3DGS_MDL3 (const unsigned char *szData)
 Load a paletized texture from the file and convert it to 32bpp. More...
 
void FreePalette (const unsigned char *pszColorMap)
 Free a palette created with a previous call to SearchPalette() More...
 
void GenerateOutputMeshes_3DGS_MDL7 (MDL::IntGroupData_MDL7 &groupData, MDL::IntSplitGroupData_MDL7 &splitGroupData)
 Generate the final output meshes for a7 models. More...
 
const aiImporterDescGetInfo () const
 Return importer meta information. More...
 
void HandleMaterialReferences_3DGS_MDL7 ()
 Handles materials that are just referencing another material There is no test file for this feature, but Conitec's doc say it is used. More...
 
void ImportUVCoordinate_3DGS_MDL345 (aiVector3D &vOut, const MDL::TexCoord_MDL3 *pcSrc, unsigned int iIndex)
 Read an UV coordinate from the file. More...
 
void InternReadFile (const std::string &pFile, aiScene *pScene, IOSystem *pIOHandler)
 Imports the given file into the given scene structure. More...
 
void InternReadFile_3DGS_MDL345 ()
 Import a GameStudio A4/A5 file (MDL 3,4,5) More...
 
void InternReadFile_3DGS_MDL7 ()
 Import a GameStudio A7 file (MDL 7) More...
 
void InternReadFile_HL2 ()
 Import a CS:S/HL2 MDL file (not fully implemented) More...
 
void InternReadFile_Quake1 ()
 Import a quake 1 MDL file (IDPO) More...
 
void JoinSkins_3DGS_MDL7 (aiMaterial *pcMat1, aiMaterial *pcMat2, aiMaterial *pcMatOut)
 Join two materials / skins. More...
 
MDL::IntBone_MDL7 ** LoadBones_3DGS_MDL7 ()
 Load the bone list of a MDL7 file. More...
 
void ParseBoneTrafoKeys_3DGS_MDL7 (const MDL::IntGroupInfo_MDL7 &groupInfo, IntFrameInfo_MDL7 &frame, MDL::IntSharedData_MDL7 &shared)
 Load bone transformation keyframes from a file chunk. More...
 
void ParseSkinLump_3DGS_MDL7 (const unsigned char *szCurrent, const unsigned char **szCurrentOut, std::vector< aiMaterial *> &pcMats)
 Parse a skin lump in a MDL7/HMP7 file with all of its features variant 1: Current cursor position is the beginning of the skin header. More...
 
void ParseSkinLump_3DGS_MDL7 (const unsigned char *szCurrent, const unsigned char **szCurrentOut, aiMaterial *pcMatOut, unsigned int iType, unsigned int iWidth, unsigned int iHeight)
 Parse a skin lump in a MDL7/HMP7 file with all of its features variant 2: Current cursor position is the beginning of the skin data. More...
 
void ParseTextureColorData (const unsigned char *szData, unsigned int iType, unsigned int *piSkip, aiTexture *pcNew)
 Parse texture color data for MDL5, MDL6 and MDL7 formats. More...
 
bool ProcessFrames_3DGS_MDL7 (const MDL::IntGroupInfo_MDL7 &groupInfo, MDL::IntGroupData_MDL7 &groupData, MDL::IntSharedData_MDL7 &shared, const unsigned char *szCurrent, const unsigned char **szCurrentOut)
 Process the frame section at the end of a group. More...
 
void ReadFaces_3DGS_MDL7 (const MDL::IntGroupInfo_MDL7 &groupInfo, MDL::IntGroupData_MDL7 &groupData)
 Read all faces and vertices from a MDL7 group. More...
 
aiColor4D ReplaceTextureWithColor (const aiTexture *pcTexture)
 Checks whether a texture can be replaced with a single color This is useful for all file formats before MDL7 (all those that are not containing material colors separate from textures). More...
 
void SearchPalette (const unsigned char **pszColorMap)
 Try to load a palette from the current directory (colormap.lmp) If it is not found the default palette of Quake1 is returned. More...
 
void SetupMaterialProperties_3DGS_MDL5_Quake1 ()
 Setup the material properties for Quake and MDL<7 models. More...
 
void SizeCheck (const void *szPos)
 Check whether a given position is inside the valid range Throw a DeadlyImportError if it is not. More...
 
void SizeCheck (const void *szPos, const char *szFile, unsigned int iLine)
 
void SkipSkinLump_3DGS_MDL7 (const unsigned char *szCurrent, const unsigned char **szCurrentOut, unsigned int iType, unsigned int iWidth, unsigned int iHeight)
 Skip a skin lump in a MDL7/HMP7 file. More...
 
void SortByMaterials_3DGS_MDL7 (const MDL::IntGroupInfo_MDL7 &groupInfo, MDL::IntGroupData_MDL7 &groupData, MDL::IntSplitGroupData_MDL7 &splitGroupData)
 Sort all faces by their materials. More...
 
void ValidateHeader_3DGS_MDL7 (const MDL::Header_MDL7 *pcHeader)
 Validate the header data structure of a game studio MDL7 file. More...
 
void ValidateHeader_Quake1 (const MDL::Header *pcHeader)
 Validate the header data structure of a Quake 1 model. More...
 

Protected Attributes

unsigned int configFrameID
 Configuration option: frame to be loaded. More...
 
std::string configPalette
 Configuration option: palette to be used to decode palletized images. More...
 
unsigned int iFileSize
 Size of the input file in bytes. More...
 
unsigned int iGSFileVersion
 For GameStudio MDL files: The number in the magic word, either 3,4 or 5 (MDL7 doesn't need this, the format has a separate loader) More...
 
unsigned char * mBuffer
 Buffer to hold the loaded file. More...
 
IOSystempIOHandler
 Output I/O handler. More...
 
aiScenepScene
 Output scene to be filled. More...
 
- Protected Attributes inherited from Assimp::BaseImporter
std::string m_ErrorText
 Error description in case there was one. More...
 
ProgressHandlerm_progress
 Currently set progress handler. More...
 

Additional Inherited Members

- Public Types inherited from Assimp::BaseImporter
enum  TextFileMode { ALLOW_EMPTY, FORBID_EMPTY }
 Enum to define, if empty files are ok or not. More...
 
- Static Public Member Functions inherited from Assimp::BaseImporter
static bool CheckMagicToken (IOSystem *pIOHandler, const std::string &pFile, const void *magic, unsigned int num, unsigned int offset=0, unsigned int size=4)
 Check whether a file starts with one or more magic tokens. More...
 
static void ConvertToUTF8 (std::vector< char > &data)
 An utility for all text file loaders. More...
 
static void ConvertUTF8toISO8859_1 (std::string &data)
 An utility for all text file loaders. More...
 
template<typename T >
static AI_FORCE_INLINE void CopyVector (std::vector< T > &vec, T *&out, unsigned int &outLength)
 Utility function to move a std::vector into a aiScene array. More...
 
static std::string GetExtension (const std::string &pFile)
 Extract file extension from a string. More...
 
static bool SearchFileHeaderForToken (IOSystem *pIOSystem, const std::string &file, const char **tokens, unsigned int numTokens, unsigned int searchBytes=200, bool tokensSol=false)
 A utility for CanRead(). More...
 
static bool SimpleExtensionCheck (const std::string &pFile, const char *ext0, const char *ext1=NULL, const char *ext2=NULL)
 Check whether a file has a specific file extension. More...
 
static void TextFileToBuffer (IOStream *stream, std::vector< char > &data, TextFileMode mode=FORBID_EMPTY)
 Utility for text file loaders which copies the contents of the file into a memory buffer and converts it to our UTF8 representation. More...
 

Detailed Description

Class to load MDL files.

Several subformats exist:

  • Quake I
  • 3D Game Studio MDL3, MDL4
  • 3D Game Studio MDL5
  • 3D Game Studio MDL7
  • Halflife 2

These formats are partially identical and it would be possible to load them all with a single 1000-line function-beast. However, it has been split into several code paths to make the code easier to read and maintain.

Constructor & Destructor Documentation

◆ MDLImporter()

MDLImporter::MDLImporter ( )

◆ ~MDLImporter()

MDLImporter::~MDLImporter ( )

Member Function Documentation

◆ AddAnimationBoneTrafoKey_3DGS_MDL7()

void MDLImporter::AddAnimationBoneTrafoKey_3DGS_MDL7 ( unsigned int  iTrafo,
const MDL::BoneTransform_MDL7 pcBoneTransforms,
MDL::IntBone_MDL7 **  apcBonesOut 
)
protected

Add a bone transformation key to an animation.

Parameters
iTrafoIndex of the transformation (always==frame index?) No need to validate this index, it is always valid.
pcBoneTransformsBone transformation for this index
apcOutBonesOutput bones array

◆ AddBonesToNodeGraph_3DGS_MDL7()

void MDLImporter::AddBonesToNodeGraph_3DGS_MDL7 ( const MDL::IntBone_MDL7 **  apcBonesOut,
aiNode pcParent,
uint16_t  iParentIndex 
)
protected

Add all bones to the nodegraph (as children of the root node)

Parameters
apcBonesOutList of bones
pcParentParent node. New nodes will be added to this node
iParentIndexIndex of the parent bone

◆ BuildOutputAnims_3DGS_MDL7()

void MDLImporter::BuildOutputAnims_3DGS_MDL7 ( const MDL::IntBone_MDL7 **  apcBonesOut)
protected

Build output animations.

Parameters
apcBonesOutList of bones

◆ CalcAbsBoneMatrices_3DGS_MDL7()

void MDLImporter::CalcAbsBoneMatrices_3DGS_MDL7 ( MDL::IntBone_MDL7 **  apcOutBones)
protected

Calculate absolute bone animation matrices for each bone.

Parameters
apcOutBonesOutput bones array

◆ CalculateUVCoordinates_MDL5()

void MDLImporter::CalculateUVCoordinates_MDL5 ( )
protected

Converts the absolute texture coordinates in MDL5 files to relative in a range between 0 and 1.

◆ CanRead()

bool MDLImporter::CanRead ( const std::string &  pFile,
IOSystem pIOHandler,
bool  checkSig 
) const
virtual

Returns whether the class can handle the format of the given file.

See BaseImporter::CanRead() for details.

Implements Assimp::BaseImporter.

◆ CopyMaterials_3DGS_MDL7()

void MDLImporter::CopyMaterials_3DGS_MDL7 ( MDL::IntSharedData_MDL7 shared)
protected

Copies only the material that are referenced by at least one mesh to the final output material list.

All other materials will be discarded.

Parameters
shared-> doc of data structure

◆ CreateTexture_3DGS_MDL4()

void MDLImporter::CreateTexture_3DGS_MDL4 ( const unsigned char *  szData,
unsigned int  iType,
unsigned int *  piSkip 
)
protected

Used to load textures from MDL3/4.

Parameters
szDataInput data
iTypeColor data type
piSkipReceive: Size to skip, in bytes

◆ CreateTexture_3DGS_MDL5()

void MDLImporter::CreateTexture_3DGS_MDL5 ( const unsigned char *  szData,
unsigned int  iType,
unsigned int *  piSkip 
)
protected

Used to load textures from MDL5.

Parameters
szDataInput data
iTypeColor data type
piSkipReceive: Size to skip, in bytes

◆ CreateTextureARGB8_3DGS_MDL3()

void MDLImporter::CreateTextureARGB8_3DGS_MDL3 ( const unsigned char *  szData)
protected

Load a paletized texture from the file and convert it to 32bpp.

◆ FreePalette()

void MDLImporter::FreePalette ( const unsigned char *  pszColorMap)
protected

Free a palette created with a previous call to SearchPalette()

◆ GenerateOutputMeshes_3DGS_MDL7()

void MDLImporter::GenerateOutputMeshes_3DGS_MDL7 ( MDL::IntGroupData_MDL7 groupData,
MDL::IntSplitGroupData_MDL7 splitGroupData 
)
protected

Generate the final output meshes for a7 models.

Parameters
groupData-> doc of data structure
splitGroupData-> doc of data structure

◆ GetInfo()

const aiImporterDesc * MDLImporter::GetInfo ( ) const
protectedvirtual

Return importer meta information.

See #BaseImporter::GetInfo for the details

Implements Assimp::BaseImporter.

◆ HandleMaterialReferences_3DGS_MDL7()

void MDLImporter::HandleMaterialReferences_3DGS_MDL7 ( )
protected

Handles materials that are just referencing another material There is no test file for this feature, but Conitec's doc say it is used.

◆ ImportUVCoordinate_3DGS_MDL345()

void MDLImporter::ImportUVCoordinate_3DGS_MDL345 ( aiVector3D vOut,
const MDL::TexCoord_MDL3 pcSrc,
unsigned int  iIndex 
)
protected

Read an UV coordinate from the file.

If the file format is not MDL5, the function calculates relative texture coordinates

Parameters
vOutReceives the output UV coord
pcSrcUV coordinate buffer
UVcoordinate index

◆ InternReadFile()

void MDLImporter::InternReadFile ( const std::string &  pFile,
aiScene pScene,
IOSystem pIOHandler 
)
protectedvirtual

Imports the given file into the given scene structure.

See BaseImporter::InternReadFile() for details

Implements Assimp::BaseImporter.

◆ InternReadFile_3DGS_MDL345()

void MDLImporter::InternReadFile_3DGS_MDL345 ( )
protected

Import a GameStudio A4/A5 file (MDL 3,4,5)

◆ InternReadFile_3DGS_MDL7()

void MDLImporter::InternReadFile_3DGS_MDL7 ( )
protected

Import a GameStudio A7 file (MDL 7)

◆ InternReadFile_HL2()

void MDLImporter::InternReadFile_HL2 ( )
protected

Import a CS:S/HL2 MDL file (not fully implemented)

◆ InternReadFile_Quake1()

void MDLImporter::InternReadFile_Quake1 ( )
protected

Import a quake 1 MDL file (IDPO)

◆ JoinSkins_3DGS_MDL7()

void MDLImporter::JoinSkins_3DGS_MDL7 ( aiMaterial pcMat1,
aiMaterial pcMat2,
aiMaterial pcMatOut 
)
protected

Join two materials / skins.

Setup UV source ... etc

Parameters
pcMat1First input material
pcMat2Second input material
pcMatOutOutput material instance to be filled. Must be empty

◆ LoadBones_3DGS_MDL7()

MDL::IntBone_MDL7 ** MDLImporter::LoadBones_3DGS_MDL7 ( )
protected

Load the bone list of a MDL7 file.

Returns
If the bones could be loaded successfully, a valid array containing pointers to a temporary bone representation. NULL if the bones could not be loaded.

◆ ParseBoneTrafoKeys_3DGS_MDL7()

void MDLImporter::ParseBoneTrafoKeys_3DGS_MDL7 ( const MDL::IntGroupInfo_MDL7 groupInfo,
IntFrameInfo_MDL7 frame,
MDL::IntSharedData_MDL7 shared 
)
protected

Load bone transformation keyframes from a file chunk.

Parameters
groupInfo-> doc of data structure
frame-> doc of data structure
shared-> doc of data structure

◆ ParseSkinLump_3DGS_MDL7() [1/2]

void MDLImporter::ParseSkinLump_3DGS_MDL7 ( const unsigned char *  szCurrent,
const unsigned char **  szCurrentOut,
std::vector< aiMaterial *> &  pcMats 
)
protected

Parse a skin lump in a MDL7/HMP7 file with all of its features variant 1: Current cursor position is the beginning of the skin header.

Parameters
szCurrentCurrent data pointer
szCurrentOutOutput data pointer
pcMatsMaterial list for this group. To be filled ...

◆ ParseSkinLump_3DGS_MDL7() [2/2]

void MDLImporter::ParseSkinLump_3DGS_MDL7 ( const unsigned char *  szCurrent,
const unsigned char **  szCurrentOut,
aiMaterial pcMatOut,
unsigned int  iType,
unsigned int  iWidth,
unsigned int  iHeight 
)
protected

Parse a skin lump in a MDL7/HMP7 file with all of its features variant 2: Current cursor position is the beginning of the skin data.

Parameters
szCurrentCurrent data pointer
szCurrentOutOutput data pointer
pcMatOutOutput material
iTypeheader.typ
iWidthheader.width
iHeightheader.height

◆ ParseTextureColorData()

void MDLImporter::ParseTextureColorData ( const unsigned char *  szData,
unsigned int  iType,
unsigned int *  piSkip,
aiTexture pcNew 
)
protected

Parse texture color data for MDL5, MDL6 and MDL7 formats.

Parameters
szDataCurrent data pointer
iTypetype of the texture data. No DDS or external
piSkipReceive the number of bytes to skip
pcNewMust point to fully initialized data. Width and height must be set. If pcNew->pcData is set to UINT_MAX, piSkip will receive the size of the texture, in bytes, but no color data will be read.

◆ ProcessFrames_3DGS_MDL7()

bool MDLImporter::ProcessFrames_3DGS_MDL7 ( const MDL::IntGroupInfo_MDL7 groupInfo,
MDL::IntGroupData_MDL7 groupData,
MDL::IntSharedData_MDL7 shared,
const unsigned char *  szCurrent,
const unsigned char **  szCurrentOut 
)
protected

Process the frame section at the end of a group.

Parameters
groupInfo-> doc of data structure
shared-> doc of data structure
szCurrentPointer to the start of the frame section
szCurrentOutReceives a pointer to the first byte of the next data section.
Returns
false to read no further groups (a small workaround for some tiny and unsolved problems ... )

◆ ReadFaces_3DGS_MDL7()

void MDLImporter::ReadFaces_3DGS_MDL7 ( const MDL::IntGroupInfo_MDL7 groupInfo,
MDL::IntGroupData_MDL7 groupData 
)
protected

Read all faces and vertices from a MDL7 group.

The function fills preallocated memory buffers.

Parameters
groupInfo-> doc of data structure
groupData-> doc of data structure

◆ ReplaceTextureWithColor()

aiColor4D MDLImporter::ReplaceTextureWithColor ( const aiTexture pcTexture)
protected

Checks whether a texture can be replaced with a single color This is useful for all file formats before MDL7 (all those that are not containing material colors separate from textures).

MED seems to write dummy 8x8 monochrome images instead.

Parameters
pcTextureInput texture
Returns
aiColor.r is set to qnan if the function fails and no color can be found.

◆ SearchPalette()

void MDLImporter::SearchPalette ( const unsigned char **  pszColorMap)
protected

Try to load a palette from the current directory (colormap.lmp) If it is not found the default palette of Quake1 is returned.

◆ SetupMaterialProperties_3DGS_MDL5_Quake1()

void MDLImporter::SetupMaterialProperties_3DGS_MDL5_Quake1 ( )
protected

Setup the material properties for Quake and MDL<7 models.

These formats don't support more than one material per mesh, therefore the method processes only ONE skin and removes all others.

◆ SetupProperties()

void MDLImporter::SetupProperties ( const Importer pImp)
virtual

Called prior to ReadFile().

The function is a request to the importer to update its configuration basing on the Importer's configuration property list.

Reimplemented from Assimp::BaseImporter.

◆ SizeCheck() [1/2]

void MDLImporter::SizeCheck ( const void *  szPos)
protected

Check whether a given position is inside the valid range Throw a DeadlyImportError if it is not.

Parameters
szPosCursor position
szFileName of the source file from which the function was called
iLineSource code line from which the function was called

◆ SizeCheck() [2/2]

void MDLImporter::SizeCheck ( const void *  szPos,
const char *  szFile,
unsigned int  iLine 
)
protected

◆ SkipSkinLump_3DGS_MDL7()

void MDLImporter::SkipSkinLump_3DGS_MDL7 ( const unsigned char *  szCurrent,
const unsigned char **  szCurrentOut,
unsigned int  iType,
unsigned int  iWidth,
unsigned int  iHeight 
)
protected

Skip a skin lump in a MDL7/HMP7 file.

Parameters
szCurrentCurrent data pointer
szCurrentOutOutput data pointer. Points to the byte just behind the last byte of the skin.
iTypeheader.typ
iWidthheader.width
iHeightheader.height

◆ SortByMaterials_3DGS_MDL7()

void MDLImporter::SortByMaterials_3DGS_MDL7 ( const MDL::IntGroupInfo_MDL7 groupInfo,
MDL::IntGroupData_MDL7 groupData,
MDL::IntSplitGroupData_MDL7 splitGroupData 
)
protected

Sort all faces by their materials.

If the mesh is using multiple materials per face (that are blended together) the function might create new materials.

Parameters
groupInfo-> doc of data structure
groupData-> doc of data structure
splitGroupData-> doc of data structure

◆ ValidateHeader_3DGS_MDL7()

void MDLImporter::ValidateHeader_3DGS_MDL7 ( const MDL::Header_MDL7 pcHeader)
protected

Validate the header data structure of a game studio MDL7 file.

Parameters
pcHeaderInput header to be validated

◆ ValidateHeader_Quake1()

void MDLImporter::ValidateHeader_Quake1 ( const MDL::Header pcHeader)
protected

Validate the header data structure of a Quake 1 model.

Parameters
pcHeaderInput header to be validated

Member Data Documentation

◆ configFrameID

unsigned int Assimp::MDLImporter::configFrameID
protected

Configuration option: frame to be loaded.

◆ configPalette

std::string Assimp::MDLImporter::configPalette
protected

Configuration option: palette to be used to decode palletized images.

◆ iFileSize

unsigned int Assimp::MDLImporter::iFileSize
protected

Size of the input file in bytes.

◆ iGSFileVersion

unsigned int Assimp::MDLImporter::iGSFileVersion
protected

For GameStudio MDL files: The number in the magic word, either 3,4 or 5 (MDL7 doesn't need this, the format has a separate loader)

◆ mBuffer

unsigned char* Assimp::MDLImporter::mBuffer
protected

Buffer to hold the loaded file.

◆ pIOHandler

IOSystem* Assimp::MDLImporter::pIOHandler
protected

Output I/O handler.

used to load external lmp files

◆ pScene

aiScene* Assimp::MDLImporter::pScene
protected

Output scene to be filled.


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