MQDocument class

MQDocument class manages objects, materials and so on.

Object
GetObjectCount Get a number of object in this document.
GetObject Get a pointer of the object class by an index.
GetObjectFromUniqueID Get a pointer of the object class by an unique ID.
GetCurrentObjectIndex Get an index of the current object.
SetCurrentObjectIndex Set an index of the current object.
AddObject Add an object to this document.
InsertObject Add an object after the specified object.
DeleteObject Remove the object from the document and delete it.
GetObjectIndex Get an index of the specified object.
GetParentObject Get a parent object of the specified object.
GetChildObjectCount Get a number of children object of the specified object.
GetChildObject Get a child object of the specified object.
GetGlobalMatrix Get a global transformation matrix of the specified object.
GetGlobalInverseMatrix Get an inverse global transformation matrix of the specified object.
GetUnusedObjectName Get an unused object name.
Triangulate Divide a polygon into multiple triangles
Material
GetMaterialCount Get a number of materials in this document.
GetMaterial Get a pointer of a material class by an index.
GetMaterialFromUniqueID Get a pointer of a material class by an unique ID.
GetCurrentMaterialIndex Get an index of the current material.
SetCurrentMaterialIndex Set an index of the current material.
AddMaterial Add a material to this document.
DeleteMaterial Remove the material from this document, and delete it.
GetUnusedMaterialName Get an unused material name.
Memory
Compact Shorten arrays in the document by removing NULLs.
Selection
ClearSelect Clear all the selection of the vertices, lines and faces.
AddSelectVertex Select a vertex.
DeleteSelectVertex Deselect a vertex.
IsSelectVertex Check if the vertex is selected.
AddSelectLine Select a line.
DeleteSelectLine Deselect a line.
IsSelectLine Check if the line is selected.
AddSelectFace Select a face.
DeleteSelectFace Deselect a face.
IsSelectFace Check if the face is selected.
AddSelectUVVertex Select a UV vertex.
DeleteSelectUVVertex Deselect a UV vertex.
IsSelectUVVertex Check if the UV vertex is selected.
User data
CreateObjectUserData Create an user data ID for an object.
DeleteObjectUserData Delete an user data ID for an object.
FindObjectUserData Find an user data ID for an object.
CreateVertexUserData Create an user data ID for vertices.
DeleteVertexUserData Delete an user data ID for vertices.
FindVertexUserData Find an user data ID for vertices.
CreateFaceUserData Create an user data ID for faces.
DeleteFaceUserData Delete an user data ID for faces.
FindFaceUserData Find an user data ID for face.
CreateMaterialUserData Create an user data ID for a material.
DeleteMaterialUserData Delete an user data ID for a material.
FindMaterialUserData Find an user data ID for a material.
Mapping
FindMappingFile Convert a filename to an absolute path.
GetMappingImageSize Get a size of a mapping image.
GetMappingImage Get a mapping image.
Scene
GetScene Get a scene.

int MQDocument::GetObjectCount(void);

Return value
A size of array of the objects

It gets a number of objects contained in this document.

This function returns not a number of objects exist actually but a size of array of the objects. So, it contains NULL objects deleted by MQDocument::DeleteObject(). To get an actual number, you must count non-NULL objects by MQDocument::GetObject().


MQObject MQDocument::GetObject(int index);

index
An index of the object
Return value
Object class

It gets a pointer of the specified indexed object.

It returns NULL if an object at the specified index does not exist.


MQObject MQDocument::GetObjectFromUniqueID(int id);

id
An unique ID for an object
Return value
An object class

It gets a pointer of an object that has the specified unique ID.

It returns NULL if an object with the specified unique ID does not exist.


int MQDocument::GetCurrentObjectIndex(void);

Return value
An index of the current object

It gets an index of the current object.

A status of multiple selections can be obtained by MQObject::GetSelected().


void MQDocument::SetCurrentObjectIndex(int index);

index
An index of an object to be current

It specifies a current object with an index.

A status of multiple selections can be set by MQObject::SetSelected().


int MQDocument::AddObject(MQObject obj);

obj
An object to be added
Return value
An index of the added object

It adds an object to this document.

Since the object is managed by the document after adding, you must not delete the object by MQObject::DeleteThis().


int MQDocument::InsertObject(MQObject obj, MQObject before);

obj
An object to be added
before
'obj' will be inserted behind this 'before' object (in a head if 'before' is NULL)
Return value
An index of the added object

(new in Rev2.41)

It registers an object to the document after the specified object. The object will be registered in the head of the list if 'before' is NULL. An index of an object behind the inserted object in a list will be changed.

The material is managed by this document. So, you must not delete the material by MQObject::DeleteThis().


void MQDocument::DeleteObject(int index);

index
An index of the object to be deleted

It remove the specified object from this document, and delete the object.

MQDocument::GetObject() with the deleted index will return NULL.


int MQDocument::GetObjectIndex(MQObject obj);

obj
An object class
Return value
An index of the object

It gets an index of the specified object in this document.

It returns -1 if the object does not exist in this document.


MQObject MQDocument::GetParentObject(MQObject obj);

obj
A child object
Return value
A parent object

(new in Rev2.40)

It gets a parent object of the specified object in this document.

It returns NULL if the specified object exists at the root.


int MQDocument::GetChildObjectCount(MQObject obj);

obj
A parent object
Return value
A number of the child objects

(new in Rev2.40)

It gets a number of child objects of the specified parent object in this document.

Only the objects in directly under are counted as child objects, and below it does not count grandchildren.


MQObject MQDocument::GetChildObject(MQObject obj, int index);

obj
A parent object
index
An index of a child object
Return value
A child object

(new in Rev2.40)

It gets a child object of the specified parent object in this document.

An index must be smaller value than the number returned by MQDocument::GetChildObjectCount().


void MQDocument::GetGlobalMatrix(MQObject obj, MQMatrix& mtx);

obj
An object
mtx
[OUT] A global transformation matrix

(new in Rev2.40)

It gets a global transformation matrix of the specified object in this document.


void MQDocument::GetGlobalInverseMatrix(MQObject obj, MQMatrix& mtx);

obj
An object
mtx
[OUT] An inverse global transformation matrix

(new in Rev2.40)

It gets an inverse global transformation matrix of the specified object in this document.


void MQDocument::GetUnusedObjectName(char *buffer, int buffer_size);

void MQDocument::GetUnusedObjectName(char *buffer, int buffer_size, const char *base_name);

buffer
[OUT] A buffer for storing a name
buffer_size
A size of the buffer (in bytes)
base_name
A based name

(new in Rev3.10)

It returns a name that is not used by other objects in the document.

It makes a continuous name when base_name is specified (Ex: test1 -> test2), and it makes an appropriate name when base_name is NULL or not specified.


BOOL MQDocument::Triangulate(const MQPoint *points, int points_num, int *index_array, int index_num);

points
An array of points
points_num
A number of points
index_array
A buffer for an array of indices
index_num
A size of an array of indices

(new in Rev4.00)

It divides a polygon into multiple triangles.

It returns three indices for each triangle into 'index_array'. 'index_num' must be (points_num-2)*3 or larger.


int MQDocument::GetMaterialCount(void);

Return value
A length of an array for materials

It gets a number of an array for material.

It is not a number of material exist in document but a length of an array for material. It contains NULL material deleted by MQDocument::DeleteMaterial(). You must count non-NULL materials if you want to an actual number of material in the document.


MQMaterial MQDocument::GetMaterial(int material);

material
An index of a material
Return value
A material class

It gets a pointer of the material at the specified index.

It returns NULL if a material at the specified index does not exist.


MQMaterial MQDocument::GetMaterialFromUniqueID(int id);

id
An unique ID
Return value
A material class

It gets a pointer of a material that has the specified unique ID.

It returns NULL if a material with the specified unique ID does not exist.


int MQDocument::GetCurrentMaterialIndex(void);

Return value
An index of the current material

It gets an index of the current material. No material is selected when it returns -1.


void MQDocument::SetCurrentMaterialIndex(int index);

index
An index of a material

It specifies a current material by the index.


int MQDocument::AddMaterial(MQMaterial mat);

mat
A material to be added
Return value
An index of the added material

It adds a material into the document.

Since the material is managed by the document after adding, you must not delete the material MQMaterial::DeleteThis().


void MQDocument::DeleteMaterial(int index);

index
An index of a material to be deleted

It removes the material from the document, and delete the material.

MQDocument::GetMaterial() with the deleted index will return NULL.


void MQDocument::GetUnusedMaterialName(char *buffer, int buffer_size);

void MQDocument::GetUnusedMaterialName(char *buffer, int buffer_size, const char *base_name);

buffer
[OUT] A buffer for storing a name
buffer_size
A size of the buffer (in bytes)
base_name
A based name

(new in Rev3.10)

It returns a name that is not used by other materials in the document.

It makes a continuous name when base_name is specified (Ex: test1 -> test2), and it makes an appropriate name when base_name is NULL or not specified.


void MQDocument::Compact(void);

It shortens arrays for objects or material in this document by removing NULLs in the arrays. The size of the array will be same as the number of the objects or materials actually exist in the document. And the arrays for the vertices or faces in objects are also shortened. Please be careful that the indices of vertices and faces will be changed.

Since data volume becomes small, it is desirable to perform this API after performing large operation to a document or objects. And this function is automatically called at the time of saving a file.


void MQDocument::ClearSelect(DWORD flag);

flag
[MQDOC_CLEARSELECT_VERTEX] Vertex
[MQDOC_CLEARSELECT_LINE] Line
[MQDOC_CLEARSELECT_FACE] Face
[MQDOC_CLEARSELECT_ALL] All the elements

It clears all the selection of the specified element(s).


BOOL MQDocument::AddSelectVertex(int objindex, int vertindex);

BOOL MQDocument::AddSelectVertex(MQSelectVertex sel);

objindex
An index of an object
vertindex
An index of a vertex
sel
A vertex
Return value
Succeeded or failed

It selects the specified vertex.


BOOL MQDocument::DeleteSelectVertex(int objindex, int vertindex);

BOOL MQDocument::DeleteSelectVertex(MQSelectVertex sel);

objindex
An index of an object
vertindex
An index of a vertex
sel
A vertex
Return value
Succeeded or failed

It deselects the specified vertex.


BOOL MQDocument::IsSelectVertex(int objindex, int vertindex);

BOOL MQDocument::IsSelectVertex(MQSelectVertex sel);

objindex
An index of an object
vertindex
An index of a vertex
sel
A vertex
Return value
[TRUE] The vertex is selected
[FALSE] The vertex is not selected, or does not exist

It checks if the specified vertex is selected.


BOOL MQDocument::AddSelectLine(int objindex, int faceindex, int lineindex);

BOOL MQDocument::AddSelectLine(MQSelectLine sel);

objindex
An index of an object
faceindex
An index of a face
lineindex
An index of a line
sel
A line
Return value
Succeeded or failed

It selects the specified line.


BOOL MQDocument::DeleteSelectLine(int objindex, int faceindex, int linelidex);

BOOL MQDocument::DeleteSelectLine(MQSelectLine sel);

objindex
An index of an object
faceindex
An index of a face
lineindex
An index of a line
sel
A line
Return value
Succeeded or failed

It deselects the specified line.


BOOL MQDocument::IsSelectLine(int objindex, int faceindex, int lineindex);

BOOL MQDocument::IsSelectLine(MQSelectLine sel);

objindex
An index of an object
faceindex
An index of a face
lineindex
An index of a line
sel
A line
Return value
[TRUE] The line is selected
[FALSE] The line is not selected, or it does not exist

It checks if the specified line is selected.


BOOL MQDocument::AddSelectFace(int objindex, int faceindex);

BOOL MQDocument::AddSelectFace(MQSelectFace sel);

objindex
An index of an object
faceindex
An index of a face
sel
A face
Return value
Succeeded or failed

It selects the specified face.


BOOL MQDocument::DeleteSelectFace(int objindex, int faceindex);

BOOL MQDocument::DeleteSelectFace(MQSelectFace sel);

objindex
An index of an object
faceindex
An index of a face
sel
A face
Return value
Succeeded or failed

It deselects the specified face.


BOOL MQDocument::IsSelectFace(int objindex, int faceindex);

BOOL MQDocument::IsSelectFace(MQSelectFace sel);

objindex
An index of an object
faceindex
An index of a face
sel
A face
Return value
[TRUE] The face is selected
[FALSE] The face is not selected, or it does not exists

It checks if the specified face is selected.


BOOL MQDocument::AddSelectUVVertex(int objindex, int faceindex, int vertindex);

objindex
An index of an object
faceindex
An index of a face
vertindex
An index of a vertex in a face
Return value
Succeeded or failed

(new in Rev2.30)

It selects the specified UV vertex.


BOOL MQDocument::DeleteSelectUVVertex(int objindex, int faceindex, int vertindex);

objindex
An index of an object
faceindex
An index of a face
vertindex
An index of a vertex in a face
Return value
Succeeded or failed

(new in Rev2.30)

It deselects the specified UV vertex.


BOOL MQDocument::IsSelectUVVertex(int objindex, int faceindex, int vertindex);

objindex
An index of an object
faceindex
An index of a face
vertindex
An index of a vertex in a face
Return value
[TRUE] The UV vertex is selected
[FALSE] The UV vertex is not selected, or does not exist

(new in Rev2.30)

It checks if the specified UV vertex is selected.


int MQDocument::CreateObjectUserData(DWORD productID, DWORD pluginID, const char *identifier, int bytes_per_object);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
bytes_per_object
A size of data attached for each object in bytes (max. 65535 bytes)
Return value
[Except 0] An user data ID for an object
[0] Failed

(new in Rev3.10)

It generates an user data ID for assigning plug-in own arbitrary data to each object.

productID and pluginID must be specified values obtained by MQGetPlugInID(). bytes_per_object is a size of data assigned for each object (in bytes). The maximum size for each object is 65535.

A generated user data ID is available for MQObject::AllocUserData() and so on.

When the same values are specified for productID, pluginID and identifier, a new user data is not created and the existing user data ID will be returned. You can generate multiple user data by specifying different strings for identifier.


void MQDocument::DeleteObjectUserData(int userdata_id);

userdata_id
An user data ID for an object

(new in Rev3.10)

It deletes an user data ID generated by MQDocument::CreateObjectUserData(). If user data is allocated in an object, the data will be also deleted automatically when this function is called.

It is not necessary for creating and deleting user data IDs repeatedly. Please call this function only when the user data become unnecessary completely.


int MQDocument::FindObjectUserData(DWORD productID, DWORD pluginID, const char *identifier);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
Return value
[Except 0] An user data ID for an object
[0] Not found

(new in Rev3.10)

It finds user data ID generated by CreateObjectUserData(). It returns 0 if an user data with the specified identifier does not exist.


int MQDocument::CreateVertexUserData(DWORD productID, DWORD pluginID, const char *identifier, int bytes_per_vertex);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
bytes_per_vertex
A size of data attached for each vertex in bytes (max. 65535 bytes)
Return value
[Except 0] An user data ID for vertices
[0] Failed

(new in Rev3.10)

It generates an user data ID for assigning plug-in own arbitrary data to each vertex.

productID and pluginID must be specified values obtained by MQGetPlugInID(). bytes_per_vertex is a size of data assigned for each vertex (in bytes). The maximum size for each vertex is 65535.

A generated user data ID is available for MQObject::AllocVertexUserData() and so on.

When the same values are specified for productID, pluginID and identifier, a new user data is not created and the existing user data ID will be returned. You can generate multiple user data by specifying different strings for identifier.


void MQDocument::DeleteVertexUserData(int userdata_id);

userdata_id
An user data ID for vertices

(new in Rev3.10)

It deletes an user data ID generated by MQDocument::CreateVertexUserData(). If user data are allocated in vertices, the data will be also deleted automatically when this function is called.

It is not necessary for creating and deleting user data IDs repeatedly. Please call this function only when the user data become unnecessary completely.


int MQDocument::FindVertexUserData(DWORD productID, DWORD pluginID, const char *identifier);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
Return value
[Except 0] An user data ID for vertices
[0] Not found

(new in Rev3.10)

It finds user data ID generated by CreateVertexUserData(). It returns 0 if an user data with the specified identifier does not exist.


int MQDocument::CreateFaceUserData(DWORD productID, DWORD pluginID, const char *identifier, int bytes_per_face);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
bytes_per_face
A size of data attached for each vertex in bytes (max. 65535 bytes)
Return value
[Except 0] An user data ID for faces
[0] Failed

(new in Rev3.10)

It generates an user data ID for assigning plug-in own arbitrary data to each face.

productID and pluginID must be specified values obtained by MQGetPlugInID(). bytes_per_face is a size of data assigned for each face (in bytes). The maximum size for each face is 65535.

A generated user data ID is available for MQObject::AllocFaceUserData() and so on.

When the same values are specified for productID, pluginID and identifier, a new user data is not created and the existing user data ID will be returned. You can generate multiple user data by specifying different strings for identifier.


void MQDocument::DeleteFaceUserData(int userdata_id);

userdata_id
An user data ID for faces

(new in Rev3.10)

It deletes an user data ID generated by MQDocument::CreateFaceUserData(). If user data are allocated in faces, the data will be also deleted automatically when this function is called.

It is not necessary for creating and deleting user data IDs repeatedly. Please call this function only when the user data become unnecessary completely.


int MQDocument::FindFaceUserData(DWORD productID, DWORD pluginID, const char *identifier);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
Return value
[Except 0] An user data ID for faces
[0] Not found

(new in Rev3.10)

It finds user data ID generated by CreateFaceUserData(). It returns 0 if an user data with the specified identifier does not exist.


int MQDocument::CreateMaterialUserData(DWORD productID, DWORD pluginID, const char *identifier, int bytes_per_material);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
bytes_per_material
A size of data attached for each material in bytes (max. 65535 bytes)
Return value
[Except 0] An user data ID for a material
[0] Failed

(new in Rev3.10)

It generates an user data ID for assigning plug-in own arbitrary data to each material.

productID and pluginID must be specified values obtained by MQGetPlugInID(). bytes_per_material is a size of data assigned for each material (in bytes). The maximum size for each material is 65535.

A generated user data ID is available for MQMaterial::AllocUserData() and so on.

When the same values are specified for productID, pluginID and identifier, a new user data is not created and the existing user data ID will be returned. You can generate multiple user data by specifying different strings for identifier.


void MQDocument::DeleteMaterialUserData(int userdata_id);

userdata_id
An user data ID for a material

(new in Rev3.10)

It deletes an user data ID generated by MQDocument::CreateMaterialUserData(). If user data are allocated in a material, the data will be also deleted automatically when this function is called.

It is not necessary for creating and deleting user data IDs repeatedly. Please call this function only when the user data become unnecessary completely.


int MQDocument::FindMaterialUserData(DWORD productID, DWORD pluginID, const char *identifier);

productID
A product ID
pluginID
A plug-in ID
identifier
An arbitrary string for indentifying (max. 15 characters)
Return value
[0??O] An user data ID for a material
[0] Not found

(new in Rev3.10)

It finds user data ID generated by CreateMaterialUserData(). It returns 0 if an user data with the specified identifier does not exist.


BOOL MQDocument::FindMappingFile(char *out_path, const char *filename, DWORD map_type);
BOOL MQDocument::FindMappingFile(wchar_t *out_path, const wchar_t *filename, DWORD map_type);

outpath
A buffer to receive an absolute path (ANSI or Wide string)
filename
A filename (ANSI or Wide string)
map_type
A type of a mapping image
[MQMAPPING_TEXTURE] A texture mapping
[MQMAPPING_ALPHA] An alpha mapping
[MQMAPPING_BUMP] A bump mapping
[MQMAPPING_HLSL] A mapping for HLSL shader
Return value
[TRUE] Succeed
[FALSE] Failed

(new in Rev2.10)

It converts a filename get by MQMaterial::GetTextureName(), GetAlphaName() or GetBumpName() to an absolute path.

The size of 'outpath' must be equal to or larger than MAX_PATH.


BOOL MQDocument::GetMappingImageSize(const char *filename, DWORD map_type, int& width, int& height);

filename
A filename
map_type
A type of a mapping image
[MQMAPPING_TEXTURE] A texture mapping
[MQMAPPING_ALPHA] An alpha mapping
[MQMAPPING_BUMP] A bump mapping
width
[OUT] Width of the mapping image (in pixels)
height
[OUT] Height of the mapping image (in pixels)
Return value
[TRUE] Succeed
[FALSE] Failed

(new in Rev3.10)

It gets a size of a mapping image which has the specified file name.

The mapping image must have been already loaded. It still cannot get immediately after setting by MQMaterial::SetTextureName() and so on.


BOOL MQDocument::GetMappingImage(const char *filename, DWORD map_type, int& width, int& height, int& bpp, const RGBQUAD*& colors, const BYTE*& buffer);
BOOL MQDocument::GetMappingImage(const wchar_t *filename, DWORD map_type, int& width, int& height, int& bpp, const RGBQUAD*& colors, const BYTE*& buffer);

filename
A filename (ANSI or Wide string)
map_type
A type of a mapping image
bpp
[OUT] Bit per pixel
colors
[OUT] Color palettes
buffer
[OUT] An image buffer
[MQMAPPING_TEXTURE] A texture mapping
[MQMAPPING_ALPHA] An alpha mapping
[MQMAPPING_BUMP] A bump mapping
width
[OUT] Width of the mapping image (in pixels)
height
[OUT] Height of the mapping image (in pixels)
Return value
[TRUE] Succeed
[FALSE] Failed

(new in Rev4.10)

It gets a mapping image which has the specified file name.

The mapping image must have been already loaded. It still cannot get immediately after setting by MQMaterial::SetTextureName() and so on.

When 'bpp' is equal or less than 8, 'colors' have color palettes. And when it is larger than 8, 'colors' will be NULL.

'buffer' contains an image data compatible with a Windows DIB. You must not modify the image.


MQScene MQDocument::GetScene(int index);

index
An index of a scene
Return value
A scene class

(new in Rev2.10)

It gets the specified scene contained in this document.

It returns a perspective view by specifying 0 to 'index'. The 'index' must be 0 in the current version.