MQObject class

MQObject class contains vertices, faces and so on in an object.

Basic
DeleteThis Delete this object
GetUniqueID Get an unique ID of an object
GetType Get an object type
SetType Set an object type
Clone Duplicate an object
Clear Delete all vertices and faces
Merge Merge two objects
Freeze Polygonize attributes such as a patch or a mirroring
GetName Get an object's name
SetName Set an object's name
GetSelected Get a selection status of an object
SetSelected Set a selection status of an object
Vertex
GetVertexCount Get a number of vertices
GetVertex Get a position of a vertex
SetVertex Set a position of a vertex
GetVertexArray Get positions of all the vertices
ReserveVertex Reserve a vertex buffer
AddVertex Add a vertex
DeleteVertex Delete a vertex
GetVertexRefCount Get a reference count of a vertex
GetVertexUniqueID Get an unique ID assigned to a vertex
GetVertexIndexFromUniqueID Get an index of a vertex that the specified unique ID is assigned to
GetVertexRelatedFaces Get faces shared with a vertex
GetVertexWeight Get a weight for a patch in a face
SetVertexWeight Set a weight for a patch in a face
CopyVertexAttribute Copy vertex attributes to the other vertex
Face
GetFaceCount Get a number of faces
GetFacePointCount Get a number of vertices in a face
GetFacePointArray Get indices of vertices in a face
GetFaceCoordinateArray Get UV coordinates of vertices in a face
SetFaceCoordinateArray Set UV coordinates of vertices in a face
GetFaceVertexColor Get a vertex color in a face
SetFaceVertexColor Get a vertex color in a face
GetFaceVertexNormal Get a vertex normal and a crease of an edge in a face
SetFaceVertexNormal Set a vertex normal and a crease of an edge in a face
GetFaceEdgeCrease Get a sharp crease of an edge in a face
SetFaceEdgeCrease Set a sharp crease of an edge in a face
GetFaceVisible Get a visibility of a face
SetFaceVisible Set a visibility of a face
GetFaceMaterial Get an index of a material assigned to a face
SetFaceMaterial Assign a material to a face
GetFaceUniqueID Get an unique ID assigned to a face
GetFaceIndexFromUniqueID Get an index of a face by an unique ID
ReserveFace Reserve a face buffer
AddFace Add a face
InsertFace Insert a face into the specified index
DeleteFace Delete a face
InvertFace Invert a direction of a face
Misc
OptimizeVertex Combine vertices in the specified distance
Compact Compact indices of vertices and faces
Attribute
GetVisible Get a visibility of the object
SetVisible Set a visibility of the object
GetPatchType Get a patch type
SetPatchType Set a patch type
GetPatchSegment Get a division number of a patch
SetPatchSegment Set a division number of a patch
GetPatchTriangle Get a method of a division for triangles in Catmull-Clark
SetPatchTriangle Set a method of a division for triangles in Catmull-Clark
GetPatchSmoothTriangle Get a method of a smoothing for triangles in OpenSubdiv
SetPatchSmoothTriangle Set a method of a smoothing for triangles in OpenSubdiv
GetPatchLimitSurface Get an application of a limit surface in OpenSubdiv
SetPatchLimitSurface Set an application of a limit surface in OpenSubdiv
GetPatchMeshInterp Get an interpolation method for open faces
SetPatchMeshInterp Set an interpolation method for open faces
GetPatchUVInterp Get an interpolation method for UV borders
SetPatchUVInterp Set an interpolation method for UV borders
GetShading Get a smoothing type
SetShading Set a smoothing type
GetSmoothAngle Get a smoothing angle
SetSmoothAngle Set a smoothing angle
GetMirrorType Get a type of a mirroring
SetMirrorType Set a type of a mirroring
GetMirrorAxis Get an axis for a mirroring
SetMirrorAxis Set an axis for a mirroring
GetMirrorDistance Get a connection distance for a mirroring
SetMirrorDistance Set a connection distance for a mirroring
GetLatheType Get a lathe type
SetLatheType Set a lathe type
GetLatheAxis Get an axis of a lathe
SetLatheAxis Set an axis of a lathe
GetLatheSegment Get a division number of a lathe
SetLatheSegment Set a division number of a lathe
GetDepth Get a depth of the hierarchy
SetDepth Set a depth of the hierarchy
GetFolding Check if the child object is invisible by holding up
SetFolding Hold the child object up and make it invisible
GetLocking Get whether the editing is prohibited
SetLocking Set whether to prohibit the editing
GetColor Get a displayed color for vertices and lines
SetColor Set a displayed color for vertices and lines
GetColorValid Get whether th displayed color is valid
SetColorValid Set whether th displayed color is valid
Local coordinate
GetScaling Get a scaling factor in a local coordinate
SetScaling Set a scaling factor in a local coordinate
GetRotation Get a rotation in a local coordinate
SetRotation Set a rotation in a local coordinate
GetTranslation Get a translation in a local coordinate
SetTranslation Set a translation in a local coordinate
GetLocalMatrix Get a transformation matrix in a local coordinate
SetLocalMatrix Set a transformation matrix in a local coordinate
GetLocalInverseMatrix Get an inverse transformation matrix in a local coordinate
Lighting parameter
GetLightValue Get a light intensity
SetLightValue Set a light intensity
GetLightAttenuation Get a light attenuation
SetLightAttenuation Set a light attenuation
GetLightFallOffEnd Get a fall-off distance of a light
SetLightFallOffEnd Set a fall-off distance of a light
GetLightFallOffHalf Get a half-attenuation distance of a light
SetLightFallOffHalf Set a half-attenuation distance of a light
Rendering flags
AddRenderFlag Display the item forcely
RemoveRenderFlag Cancel the force displaying
AddRenderEraseFlag Hide the item forcely
RemoveRenderEraseFlag Cancel the force hiding
User data
AllocUserData Allocate an object user data
FreeUserData Free an object user data
GetUserData Get an object user data
GetUserDataPart Get an object user data partially
SetUserData Set an object user data
SetUserDataPart Set an object user data partially
AllocVertexUserData Allocate a vertex user data
FreeVertexUserData Free a vertex user data
GetVertexUserData Get a vertex user data
GetVertexUserDataPart Get a vertex user data partially
SetVertexUserData Set a vertex user data
SetVertexUserDataPart Set a vertex user data partially
AllocFaceUserData Allocate a face user data
FreeFaceUserData Free a face user data
GetFaceUserData Get a face user data
GetFaceUserDataPart Get a face user data partially
SetFaceUserData Set a face user data
SetFaceUserDataPart Set a face user data partially

void MQObject::DeleteThis(void);

It deletes an object class.

This function is available for the object registered in a document. You must use MQDocument::DeleteObject() to delete an object that is not registered to any documents.


UINT MQObject::GetUniqueID(void);

Return value
An unique ID

(new in Rev2.40)

It gets an unique ID of this object.

An unique ID is assigned when an object is registered to the document by MQDocument::AddObject(). The Clone() function does not duplicate an unique ID.


int MQObject::GetType(void);

Return value
A type of the object
[MQOBJECT_TYPE_NORMAL] Normal object
[MQOBJECT_TYPE_POINT_LIGHT] Point light source
[MQOBJECT_TYPE_DIRECTIONAL_LIGHT] Parallel light source

(new in Rev3.00)

It gets a type of this object.


void MQObject::SetType(int type);

type
A type of the object
[MQOBJECT_TYPE_NORMAL] Normal object
[MQOBJECT_TYPE_POINT_LIGHT] Point light source
[MQOBJECT_TYPE_DIRECTIONAL_LIGHT] Parallel light source

(new in Rev3.00)

It sets a type of this object.


MQObject MQObject::Clone(void);

Return value
A duplicated object class

It duplicates this object class.


void MQObject::Clear(void);

(new in Rev4.59)

It deletes all vertices and faces in the object.


BOOL MQObject::Merge(MQObject source);

source
A source object
Return value
Succeeded or failed

The 'source' object merges to this object. A content of the 'source' object is not changed.

(in Rev4.64) The return value has been changed from void to BOOL, and you can detect out of memory.


BOOL MQObject::Freeze(DWORD flag);

flag
Flags of each attribute (Multiple flags are selectable)
[MQOBJECT_FREEZE_PATCH] Patch
[MQOBJECT_FREEZE_MIRROR] Mirroring
[MQOBJECT_FREEZE_LATHE] Lathe
[MQOBJECT_FREEZE_ALL] All attributes
Return value
Succeeded or failed

It polygonizes attributes such as a patch or a mirroring.

(in Rev4.64) The return value has been changed from void to BOOL, and you can detect out of memory.


void MQObject::GetName(char *buffer, int size);

std::string MQObject::GetName();

std::wstring MQObject::GetNameW();

buffer
A buffer to receive a name
size
A size of the buffer

The function with arguments stores this object's name to 'buffer'. And, the function without argument returns the name as ANSI or Wide string.


void MQObject::SetName(const char *buffer);

buffer
A buffer contains a name

It sets an object's name.


BOOL MQObject::GetSelected();

Return value
Selection status

(new in Rev3.10)

it gets a selection status of the object.

This selection indicates a status for multiple selections on the object panel. A current object can be obtained by MQDocument::GetCurrentObjectIndex().


void MQObject::SetSelected(BOOL flag);

flag
Selection status

(new in Rev3.10)

it sets a selection status of the object.

This selection indicates a status for multiple selections on the object panel. A current object can be set by MQDocument::SetCurrentObjectIndex().


int MQObject::GetVertexCount(void);

Return value
A number of an array for vertices

It gets a number of vertices.

The return value is not a number of vertices actually exist but a size of an array for vertices that contain deleted vertices. It is necessary to check whether MQObject::GetVertexRefCount() returns except 0 for each vertex to count an actual number of the vertices.


MQPoint MQObject::GetVertex(int index);

index
An index of a vertex
Return value
A position of the vertex

It gets a position of the specified vertex.
This function must be used for vertices return nonzero by MQObject::GetVertexRefCount().


void MQObject::SetVertex(int index, MQPoint pts);

index
An index of the vertex
pts
A position of the vertex

It sets a position of the specified vertex


void MQObject::GetVertexArray(MQPoint *ptsarray);

ptsarray
An array of positions to receive

It gets positions of all the vertices in this object.
An number of an array of the 'ptsarray' must be equal to or larger than the number returned by MQObject::GetVertexCount().


BOOL MQObject::ReserveVertex(int size);

size
A number of vertices
Return value
Succeeded or failed

(new in Rev4.64)

It allocates a buffer for vertices.

If you know a number of vertices to add, you should call this function before calling AddVertex(). And you can also detect out of memory.


int MQObject::AddVertex(MQPoint p);

p
A position of a new vertex
Return value
An index of the added vertex

It add a new vertex to this object.

It will return -1 if it failed to allocate the vertex data for out of memory.


BOOL MQObject::DeleteVertex(int index);

index
An index of the vertex
Return value
Succeeded or failed

It deletes the specified vertex.

When a face has the specified vertex, the face will be also deleted together.

After deleting a vertex, The number returned by MQObject::GetVertexCount() will not be changed after deleting a vertex. And MQObject::GetVertexRefCount() for the specified index will return 0.


int MQObject::GetVertexRefCount(int index);

index
An index of a vertex
Return value
A reference count

It gets how many faces use the specified vertex. The vertex does not exist when it returns 0.

A reference count is set 1 by MQObject::AddVertex(). MQObject::AddFace() makes it increase by one, and MQObject::DeleteFace() makes it decrease by one.


UINT MQObject::GetVertexUniqueID(int index);

index
An index of the vertex
Return value
An unique ID of the vertex

(new in Rev2.40)

It gets an unique ID assigned to the specified vertex.

An unique ID is a value that is not overlapped to the other IDs of the other vertices in this object. You can use to identify a particular vertex since an unique is not changed whenever an index of the vertex is changed by Compact() and so on.


int MQObject::GetVertexIndexFromUniqueID(UINT unique_id);

unique_id
An unique ID of a vertex
Return value
A index of the index (-1 if not found)

(new in Rev2.40)

It gets an index of the vertex assigned the specified unique ID. It will return -1 if the vertex has been deleted or the unique ID originally does not exist.


UINT MQObject::GetVertexRelatedFaces(int vertex, int *faces);

vertex
An index of the vertex
faces
An array to receive indices of faces
Return value
A number of faces

(new in Rev3.00)

It gets faces shared with the specified vertex. This method can process faster than brute force with MQObject::GetFacePointArray().

It only gets a number of faces when NULL is specified for faces.

If except NULL is specified for faces, indices of the faces are stored. An array of faces must be same as or larger than the returned value.


DWORD MQObject::GetVertexColor(int index);

index
An index of the vertex
Return value
Color

(in Rev2.40)

This function is obsolete. You can use MQObject::GetFaceVertexColor() to get vertex colors.


void MQObject::SetVertexColor(int index, DWORD color);

index
An index of the vertex
color
Color

(in Rev2.40)

This function is obsolete. You can use MQObject::SetFaceVertexColor() to set vertex colors.


float MQObject::GetVertexWeight(int index);

index
An index of the vertex
Return value
A weight value

It gets a weight value for a patch in the specified vertex.
The weight value will be from 0 to 1.


void MQObject::SetVertexWeight(int index, float value);

index
An index of the vertex
value
A weight value

It sets a weight value for a patch in the specified vertex.

The weight value must be from 0 to 1.


void MQObject::CopyVertexAttribute(int vert1, MQObject obj2, int vert2);

vert1
An index of the vertex in this object
obj2
A source object
vert2
An index of the vertex in 'obj2'

It copies attributes currently assigned to vert2 in obj2, such as a visibility, a fixed status, a vertex color and a weight, to vert1.


int MQObject::GetFaceCount(void);

Return value
A number of an array for faces

It gets a number of faces in this object.

The return value is not a number of faces actually exist but a size of an array for faces that contain deleted faces. It is necessary to check whether MQObject::GetFacePointCount() returns except 0 for each face to count an actual number of the faces.


int MQObject::GetFacePointCount(int face);

face
An index of the face
Return value
A number of the vertices

It gets a number of vertices in the specified face.

When 0 is returned, the face has been deleted by MQObject::DeleteFace() and it is no more.

(in Rev4.00)

Not only 4 or less but also 5 or larger number is returned for a polygon.


void MQObject::GetFacePointArray(int face, int *vertex);

face
An index of the face
vertex
A buffer to receive vertex indices

It gets an array of indices of vertices in the specified face.

The 'vertex' must be equal or larger size of an array than the number returned by MQObject::GetFacePointCount().


void MQObject::GetFaceCoordinateArray(int face, MQCoordinate *uvarray);

face
An index of the face
uvarray
A buffer to receive UV coordinates

It gets UV coordinates array of the vertices in the specified face.

The 'uvarray' must be equal or larger size of an array than the number returned by MQObject::GetFacePointCount().


void MQObject::SetFaceCoordinateArray(int face, MQCoordinate *uvarray);

face
An index of the face
uvarray
A buffer contains UV coordinates

It sets UV coordinates of the vertices in the specified face with an array.

The 'uvarray' must be equal or larger size of an array than the number returned by MQObject::GetFacePointCount().


DWORD MQObject::GetFaceVertexColor(int face, int vertex);

face
An index of the face
vertex
An index of the vertex in the face
Return value
Color

(new in Rev2.30)

It gets a vertex color of the vertex in the specified face.

The 'vertex' must be lesser than the number obtained by MQObject::GetFacePointCount().

The 32-bit DWORD of color consists of opacity (0xFF000000), red (0x000000FF), green (0x0000FF00) and blue (0x00FF0000).


void MQObject::SetFaceVertexColor(int face, int vertex, DWORD color);

face
An index of the face
vertex
An index of the vertex in the face
color
Color

(new in Rev2.30)

It sets a vertex color of the vertex in the specified face.

The 'vertex' must be lesser than the number obtained by MQObject::GetFacePointCount().

The 32-bit DWORD of color consists of opacity (0xFF000000), red (0x000000FF), green (0x0000FF00) and blue (0x00FF0000).


void MQObject::GetFaceVertexNormal(int face, int vertex, BYTE& flag, MQPoint& normal);

face
An index of the face
vertex
An index of the vertex and the edge in the face
flag
A flag of normal
[MQOBJECT_NORMAL_HARD_EDGE] creasing edge
[MQOBJECT_NORMAL_FIX] fixing normal
normal
A normal

(new in Rev4.60)

It gets a normal of the vertex and a crease of the edge in the specified face.

The 'vertex' must be lesser than the number obtained by MQObject::GetFacePointCount().


void MQObject::SetFaceVertexNormal(int face, int vertex, int type, MQPoint normal);

face
An index of the face
vertex
An index of the vertex and the edge in the face
flag
A flag of normal
[MQOBJECT_NORMAL_HARD_EDGE] creasing edge
[MQOBJECT_NORMAL_FIX] fixing normal
normal
A normal

(new in Rev4.60)

It sets a normal of the vertex and a crease of the edge in the specified face.

The 'vertex' must be lesser than the number obtained by MQObject::GetFacePointCount().


float MQObject::GetFaceEdgeCrease(int face, int line);

face
An index of a face
line
An index of an edge
Return value
Crease
[0] Round
[1] Sharp

(new in Rev3.10)

It gets a crease for a patch in a specified edge.

line must be lesser than a number returned by MQObject::GetFacePointCount().


void MQObject::SetFaceEdgeCrease(int face, int line, float crease);

face
An index of a face
line
An index of an edge
crease
Crease
[0] Round
[1] Sharp

(new in Rev3.10)

It sets a crease for a patch in the specified edge.

line must be lesser than a number returned by MQObject::GetFacePointCount().

crease must be 0 or 1 for Catmull-Clark subdivision, and be 0 or larger for OpenSubdiv subdivision.


BOOL MQObject::GetFaceVisible(int face);

face
An index of the face
Return value
A visibility

(new in Rev3.00)

It gets a visibility of the specified face.

You can use MQScene::GetVisibleFace() if you want to know the current visible state  in the scene with the view angle and display options.


void MQObject::SetFaceVisible(int face, BOOL flag);

face
An index of the face
flag
A visibility

(new in Rev3.00)

It sets a visibility of the specified face.


int MQObject::GetFaceMaterial(int face);

face
An index of the face
Return value
An index of a material

It gets an index of the material assigned to the specified face.

-1 will be returned when any material does not be assigned to the face.


void MQObject::SetFaceMaterial(int face, int material);

face
An index of the face
material
An index of a material

It assigns the material to the specified face.


UINT MQObject::GetFaceUniqueID(int face);

face
An index of the face
Return value
An unique ID of the face

(new in Rev2.40)

It gets an unique ID assigned to the specified face.

An unique ID is a value that is not overlapped to the other IDs of the other faces in this object. You can use to identify a particular face since an unique is not changed whenever an index of the face is changed by Compact() and so on.


int MQObject::GetFaceIndexFromUniqueID(UINT unique_id);

unique_id
An unique ID of the face
Return value
An index of the face (-1 if not found)

(new in Rev2.40)

It gets an index of the face with the specified unique ID. It will return -1 if the face has been deleted or the unique ID originally does not exist.


p>

BOOL MQObject::ReserveFace(int size);

size
A number of faces
Return value
Succeeded or failed

(new in Rev4.64)

It allocates a buffer for faces.

If you know a number of faces to add, you should call this function before calling AddFace(). And you can also detect out of memory.


int MQObject::AddFace(int count, int *index);

count
A number of vertices
index
A pointer to an array of indices of vertices
Return value
An index of the new face

It adds a new face to this object. The face has 'count' number of indices of vertices contained in 'index'.

It means a line when the 'count' is 2.

It returns -1 when it is impossible to allocate data for faces because the lack of the memory.


int MQObject::InsertFace(int face_index, int count, int *vert_index);

face_index
An index of the new face
count
A number of vertices
vert_index
A pointer to an array of indices of vertices
Return value
An index of the new face (equal to face_index if it succeeded.)

(new in Rev4.10)

It adds a new face into the specified index by face_index. The index of the face must be already deleted by MQObject::DeleteFace().

The face has 'count' number of indices of vertices contained in 'index'.

It means a line when the 'count' is 2.

It returns -1 when a face already exists in the specified index or it is impossible to allocate data for faces because the lack of the memory.


BOOL MQObject::DeleteFace(int index);

index
An index of the face
Return value
Succeeded or failed

It deletes the specified face.

A vertex which is contained by only this face is also deleted automatically.

After deleting, the number obtained by MQObject::GetFaceCount() is not changed, and MQObject::GetFacePointCount() with the index of the deleted face returns 0.


BOOL MQObject::InvertFace(int index);

index
An index of the face
Return value
Succeeded or failed

It inverts a direction of the face.


void MQObject::OptimizeVertex(float distance, MQBool *apply);

BOOL MQObject::OptimizeVertex(float distance, MQBool *apply, bool callback(float,void*), void *callback_data);

distance
Maximum distance to be connected
apply
Flags whether to apply for each vertex
callback
A callback function
callback_data
An arbitrary pointer to send a callback function
Return value
Succeeded or failed

It combines the vertices which are in the specified 'distance' among the vertices in this object.

When a size of an array of 'apply' is same as a number of a vertices, it can specify whether combine together for every vertex. When 'apply' is NULL, all the vertices are the targets of combination.

This method is effective after loading a file contains positions of vertices directly in each face.

(in Rev4.64) A function with return value has been added.


void MQObject::Compact(void);

It shortens arrays for vertices in this object by removing deleted vertices which return 0 by MQObject::GetVertexRefCount(), and arrays for faces by removing deleted faces which return 0 by MQObject::GetFacePointCount().

Please be careful that the indices of vertices and faces will be changed.

It is recommended to call this function after doing large operations for the object. It will make the amount of the data in this object smaller.


DWORD MQObject::GetVisible(void);

Return value
[0] Invisible
[except 0] Visible

It gets a visibility of this object.

The return value will be changed that it specifies the visibilities of the vertices, lines and faces with bit mask in the future version.


void MQObject::SetVisible(DWORD visible);

visible
[0] Invisible
[0xFFFFFFFF] Visible

It sets a visibility of this object.

The return value will be changed that it specifies the visibilities of the vertices, lines and faces with bit mask in the future version.


DWORD MQObject::GetPatchType(void);

Return value
A type of a patch
[MQOBJECT_PATCH_NONE] None
[MQOBJECT_PATCH_SPLINE1] Spline type-1
[MQOBJECT_PATCH_SPLINE2] Spline type-2
[MQOBJECT_PATCH_CATMULL] Catmull-Clark (new in Rev2.30)
[MQOBJECT_PATCH_OPENSUBDIV] OpenSubdiv (new in Rev4.00)

It gets a type of a patch specified to this object.


void MQObject::SetPatchType(DWORD type);

type
A type of a patch (same as GetPatchType())

It specifies a type of a patch to this object.


int MQObject::GetPatchSegment(void);

Return value
A division number

It gets a division number of a patch specified to this object.


void MQObject::SetPatchSegment(int segment);

segment
A division number

It specifies a division number of a patch to this object.


BOOL MQObject::GetPatchTriangle(void);

Return value
Division method
[TRUE] Divide into triangles
[FALSE] Divide into quadrangles

(new in Rev3.10)

It gets a method of a division for triangles when a Catmull-Clark subdivision scheme is applied.


void MQObject::SetPatchTriangle(BOOL flag);

flag
Division method
[TRUE] Divide into triangles
[FALSE] Divide into quadrangles

(new in Rev3.10)

It sets a method of a division for triangles when a Catmull-Clark subdivision scheme is applied.


BOOL MQObject::GetPatchSmoothTriangle(void);

Return value
Smoothing method
[TRUE] Apply smoothing
[FALSE] None

(new in Rev4.20)

It gets a method of a smoothing for triangles when a OpenSubdiv subdivision scheme is applied.


void MQObject::SetPatchSmoothTriangle(BOOL flag);

flag
Division method
[TRUE] Divide into triangles
[FALSE] None

(new in Rev4.20)

It sets a method of a smoothing for triangles when a OpenSubdiv subdivision scheme is applied.


BOOL MQObject::GetPatchLimitSurface(void);

Return value
An application of a limit surface
[TRUE] Apply a limit surface
[FALSE] None

(new in Rev4.51)

It gets whether a limit surface is applied or not when a OpenSubdiv subdivision scheme is applied.


void MQObject::SetPatchLimitSurface(BOOL flag);

flag
An application of a limit surface
[TRUE] Apply a limit surface
[FALSE] None

(new in Rev4.51)

It sets whether a limit surface is applied or not when a OpenSubdiv subdivision scheme is applied.


int MQObject::GetPatchMeshInterp(void);

Return value
An interpolation method
[MQOBJECT_INTERP_EDGE_ONLY] Edge only
[MQOBJECT_INTERP_EDGE_AND_CORNER] Edge and corner

(new in Rev4.30)

It returns an interpolation method for open faces when a OpenSubdiv subdivision scheme is applied.


void MQObject::SetPatchMeshInterp(int interp);

interp
An interpolation method
[MQOBJECT_INTERP_EDGE_ONLY] Edge only
[MQOBJECT_INTERP_EDGE_AND_CORNER] Edge and corner

(new in Rev4.30)

It specifies an interpolation method for open faces when a OpenSubdiv subdivision scheme is applied.


int MQObject::GetPatchUVInterp(void);

Return value
An interpolation method
[MQOBJECT_UVINTERP_NONE] None
[MQOBJECT_UVINTERP_CORNERS_ONLY] Corner only
[MQOBJECT_UVINTERP_CORNERS_PLUS1] Corner+1
[MQOBJECT_UVINTERP_CORNERS_PLUS2] Corner+2
[MQOBJECT_UVINTERP_BOUNDARIES] Boundaries
[MQOBJECT_UVINTERP_ALL] All

(new in Rev4.30)

It returns an interpolation method for UV borders when a OpenSubdiv subdivision scheme is applied.

(in Rev4.51) Return values have been changed to specialized values with a compatibility.


void MQObject::SetPatchUVInterp(int interp);

interp
An interpolation method
[MQOBJECT_UVINTERP_NONE] None
[MQOBJECT_UVINTERP_CORNERS_ONLY] Corner only
[MQOBJECT_UVINTERP_CORNERS_PLUS1] Corner+1
[MQOBJECT_UVINTERP_CORNERS_PLUS2] Corner+2
[MQOBJECT_UVINTERP_BOUNDARIES] Boundaries
[MQOBJECT_UVINTERP_ALL] All

(new in Rev4.30)

It specifies an interpolation method for UV borders when a OpenSubdiv subdivision scheme is applied.

(in Rev4.51) Variables have been changed to specialized values with a compatibility.


int MQObject::GetShading(void);

Return value
[MQOBJECT_SHADE_FLAT] No smoothing
[MQOBJECT_SHADE_GOURAUD] With smoothing

(new in Rev2.10)

It gets a type of a smoothing specified to this object.


void MQObject::SetShading(int type);

type
[MQOBJECT_SHADE_FLAT] No smoothing
[MQOBJECT_SHADE_GOURAUD] With smoothing

(new in Rev2.10)

It specifies a type of a smoothing to this object.


float MQObject::GetSmoothAngle(void);

Return value
A smoothing angle

(new in Rev2.10)

It gets a smoothing angle specified to this object.

The angle will be from 0 to 180.


void MQObject::SetSmoothAngle(float degree);

degree
A smoothing angle

(new in Rev2.10)

It specifies a smoothing angle specified to this object.

The 'degree' must be from 0 to 180.


int MQObject::GetMirrorType(void);

Return value
A type of mirroring
[MQOBJECT_MIRROR_NONE] None
[MQOBJECT_MIRROR_NORMAL] Mirroring without a connection of left and right side
[MQOBJECT_MIRROR_JOIN] Mirroring with a connection of left and right side

(new in Rev2.10)

It gets a type of mirroring specified to this object.


void MQObject::SetMirrorType(int type);

type
A type of mirroring
[MQOBJECT_MIRROR_NONE] None
[MQOBJECT_MIRROR_NORMAL] Mirroring without a connection of left and right side
[MQOBJECT_MIRROR_JOIN] Mirroring with a connection of left and right side

(new in Rev2.10)

It specifies a type of mirroring to this object.


DWORD MQObject::GetMirrorAxis(void);

Return value
An axis of mirroing (Multiple values are enabled)
[MQOBJECT_MIRROR_AXIS_X] X axis
[MQOBJECT_MIRROR_AXIS_Y] Y axis
[MQOBJECT_MIRROR_AXIS_Z] Z axis
[MQOBJECT_MIRROR_AXIS_LOCAL] Local coordinate (new in Rev2.40)

(new in Rev2.10)

It gets an axis of mirroring specified to this object.


void MQObject::SetMirrorAxis(DWORD axis);

axis
An axis of mirroring (Multiple values are enabled)
[MQOBJECT_MIRROR_AXIS_X] X axis
[MQOBJECT_MIRROR_AXIS_Y] Y axis
[MQOBJECT_MIRROR_AXIS_Z] Z axis
[MQOBJECT_MIRROR_AXIS_LOCAL] Local coordinate (new in Rev2.40)

(new in Rev2.10)

It specifies an axis of mirroring to this object.


float MQObject::GetMirrorDistance(void);

Return value
A maximum distance to be connected

(new in Rev2.10)

It gets a maximum distance to connect the left and right side for a mirroring.


void MQObject::SetMirrorDistance(float dis);

dis
A maximum distance to be connected

(new in Rev2.10)

It specifies a maximum distance to connect the left and right side for a mirroring.


int MQObject::GetLatheType(void);

Return value
A type of lathe
[MQOBJECT_LATHE_NONE] None
[MQOBJECT_LATHE_BOTH] A both side of a lathe

(new in Rev2.10)

It gets a type of a lathe specified to the object.


void MQObject::SetLatheType(int type);

type
A type of lathe
[MQOBJECT_LATHE_NONE] None
[MQOBJECT_LATHE_BOTH] A both side of a lathe

(new in Rev2.10)

It specifies a type of a lathe.


DWORD MQObject::GetLatheAxis(void);

Return value
An axis of lathe
[MQOBJECT_LATHE_X] X axis
[MQOBJECT_LATHE_Y] Y axis
[MQOBJECT_LATHE_Z] Z axis

(new in Rev2.10)

It gets a rotation axis of a lathe specified to the object.


void MQObject::SetLatheAxis(DWORD axis);

axis
A rotation axis
[MQOBJECT_LATHE_X] X axis
[MQOBJECT_LATHE_Y] Y axis
[MQOBJECT_LATHE_Z] Z axis

(new in Rev2.10)

It specifies a rotation axis of a lathe to the object.


int MQObject::GetLatheSegment(void);

Return value
A division number

(new in Rev2.10)

It gets a division number of a lathe specified to the object.


void MQObject::SetLatheSegment(int segment);

segment
A division number

(new in Rev2.10)

It specifies a division number of a lathe to the object.


int MQObject::GetDepth(void);

Return value
A depth of the hierarchy

(new in Rev2.40)

It gets a depth of the hierarchy of this object. 0 will be returned if this object is at the root.

A depth is not duplicated by Clone().


void MQObject::SetDepth(int depth);

depth
A depth of the hierarchy

(new in Rev2.40)

It sets a depth of the hierarchy of this object.

The object must be registered in a document. Please be careful for the mismatching of a hierarchy when you specify the depth.


BOOL MQObject::GetFolding(void);

Return value
Whether to fold the children up

(new in Rev2.40)

It gets whether the children are folded up and they are invisible in the object panel.


void MQObject::SetFolding(BOOL flag);

flag
Whether to fold the children up

(new in Rev2.40)

It sets the object to be invisible by folding up in the object panel.


BOOL MQObject::GetLocking(void);

Return value
Whether to be disabled to edit

(new in Rev2.40)

It gets whether the object is disabled to edit.


void MQObject::SetLocking(BOOL flag);

flag
[TRUE] Disabled to edit
[FALSE] Editable

(new in Rev2.40)

It sets an object to be disabled to edit or be editable.


MQColor MQObject::GetColor(void);

Return value
A displayed color for vertices and lines

(new in Rev2.40)

It returns a displayed color for vertices and lines.


void MQObject::SetColor(MQColor color);

color
A displayed color for vertices and lines

(new in Rev2.40)

It sets a displayed color for vertices and lines.

The specified color is not applied until you set TRUE inl SetColorValid().


BOOL MQObject::GetColorValid(void);

Return value
A displayed color is valid

(new in Rev2.40)

It returns whether the displayed color is valid or invalid.

When it is invalid, vertices and lines are displayed with a default color.


void MQObject::SetColorValid(BOOL flag);

color
A displayed color is valid

(new in Rev2.40)

It sets whether the displayed color is valid or invalid.

When it is invalid, vertices and lines are displayed with a default color.


MQPoint MQObject::GetScaling(void);

Return value
A scaling factor in a local coordinate

(new in Rev2.40)

It gets a scaling factor in a local coordinate.


void MQObject::SetScaling(MQPoint scale);

scale
A scaling factor in a local coordinate

(new in Rev2.40)

It sets a scaling factor in a local coordinate.


MQAngle MQObject::GetRotation(void);

Return value
A rotation angle in a local coordinate

(new in Rev2.40)

It gets a rotation angle in a local coordinate.


void MQObject::SetRotation(MQAngle angle);

angle
A rotation angle in a local coordinate

(new in Rev2.40)

It sets a rotation angle in a local coordinate.


MQPoint MQObject::GetTranslation(void);

Return value
A translation in a local coordinate

(new in Rev2.40)

It gets a translation in a local coordinate.


void MQObject::SetTranslation(MQPoint trans);

angle
A translation in a local coordinate

(new in Rev2.40)

It sets a translation in a local coordinate.


MQMatrix MQObject::GetLocalMatrix(void);

Return value
A transform matrix of a local coordinate

(new in Rev2.40)

It gets a transform matrix of a local coordinate.


void MQObject::SetLocalMatrix(const MQMatrix& mtx);

mtx
A transform matrix of a local coordinate

(new in Rev2.40)

It sets a transform matrix of a local coordinate.


MQMatrix MQObject::GetLocalInverseMatrix(void);

Return value
An inverse transform matrix of a local coordinate

(new in Rev2.40)

It gets an inverse transform matrix of a local coordinate.


float MQObject::GetLightValue(void);

Return value
An intensity of a light

(new in Rev3.00)

It gets an intensity of a light for a lighting object.


void MQObject::SetLightValue(float value);

value
An intensity of a light

(new in Rev3.00)

It sets an intensity of a light for a lighting object.


int MQObject::GetLightAttenuation(void);

Return value
A light attenuation
[0] No attenuation
[1] Linear
[2] Bilinear

(new in Rev3.00)

It gets a light attenuation from a lighting object.


void MQObject::SetLightAttenuation(int value);

value
A light attenuation
[0] No attenuation
[1] Linear
[2] Bilinear

(new in Rev3.00)

It sets a light attenuation to a lighting object.


float MQObject::GetLightFallOffEnd(void);

Return value
An end distance of a light attenuation

(new in Rev3.00)

It gets an end distance of a light attenuation from a lighting object.


void MQObject::SetLightAttenuation(float distance);

distance
An end distance of a light attenuation

(new in Rev3.00)

It sets an end distance of a light attenuation to a lighting object.


float MQObject::GetLightFallOffHalf(void);

Return value
A fall off distance to reduce by half for a light attenuation

(new in Rev3.00)

It gets a half-attenuation distance of a light from a lighting object.


void MQObject::SetLightFallOffHalf(float distance);

distance
A fall off distance to reduce by half for a light attenuation

(new in Rev3.00)

It sets a half-attenuation distance of a light to a lighting object.


void MQObject::AddRenderFlag(MQOBJECT_RENDER_FLAG flag);

flag
A type of a rendering flag
[MQOBJECT_RENDER_POINT] Show points
[MQOBJECT_RENDER_LINE] Show lines
[MQOBJECT_RENDER_FACE] Show faces
[MQOBJECT_RENDER_OVERWRITELINE] Overwrite lines
[MQOBJECT_RENDER_OVERWRITEFACE] Overwrite faces
[MQOBJECT_RENDER_ALPHABLEND] Alpha blending
[MQOBJECT_RENDER_MULTILIGHT] Multiple lights
[MQOBJECT_RENDER_SHADOW] Show shadow
[MQOBJECT_RENDER_TEXTURE] Show textures (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR] Show vertex color (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR_POINT] Show points by vertex color (new in Rev4.30)
[MQOBJECT_RENDER_SCREEN] Specify a position of a vertex on a screen coordinate (new in Rev4.50)

(new in Rev4.02)

It enabled to display the specified item forcely.

This functions is usually applied for objects created by MQStationPlugin::CreateDrawingObject().


void MQObject::RemoveRenderFlag(MQOBJECT_RENDER_FLAG flag);

flag
A type of a rendering flag
[MQOBJECT_RENDER_POINT] Show points
[MQOBJECT_RENDER_LINE] Show lines
[MQOBJECT_RENDER_FACE] Show faces
[MQOBJECT_RENDER_OVERWRITELINE] Overwrite lines
[MQOBJECT_RENDER_OVERWRITEFACE] Overwrite faces
[MQOBJECT_RENDER_ALPHABLEND] Alpha blending
[MQOBJECT_RENDER_MULTILIGHT] Multiple lights
[MQOBJECT_RENDER_SHADOW] Show shadow
[MQOBJECT_RENDER_TEXTURE] Show textures (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR] Show vertex color (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR_POINT] Show points by vertex color (new in Rev4.30)
[MQOBJECT_RENDER_SCREEN] Specify a position of a vertex on a screen coordinate (new in Rev4.50)

(new in Rev4.02)

It cancels a force display for the specified item.


void MQObject::AddRenderEraseFlag(MQOBJECT_RENDER_FLAG flag);

flag
A type of a rendering flag
[MQOBJECT_RENDER_POINT] Show points
[MQOBJECT_RENDER_LINE] Show lines
[MQOBJECT_RENDER_FACE] Show faces
[MQOBJECT_RENDER_OVERWRITELINE] Overwrite lines
[MQOBJECT_RENDER_OVERWRITEFACE] Overwrite faces
[MQOBJECT_RENDER_ALPHABLEND] Alpha blending
[MQOBJECT_RENDER_MULTILIGHT] Multiple lights
[MQOBJECT_RENDER_SHADOW] Show shadow
[MQOBJECT_RENDER_TEXTURE] Show textures (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR] Show vertex color (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR_POINT] Show points by vertex color (new in Rev4.30)
[MQOBJECT_RENDER_SCREEN] Specify a position of a vertex on a screen coordinate (new in Rev4.50)

(new in Rev4.02)

It enabled to hide the specified item forcely.

This functions is usually applied for objects created by MQStationPlugin::CreateDrawingObject().


void MQObject::RemoveRenderEraseFlag(MQOBJECT_RENDER_FLAG flag);

flag
A type of a rendering flag
[MQOBJECT_RENDER_POINT] Show points
[MQOBJECT_RENDER_LINE] Show lines
[MQOBJECT_RENDER_FACE] Show faces
[MQOBJECT_RENDER_OVERWRITELINE] Overwrite lines
[MQOBJECT_RENDER_OVERWRITEFACE] Overwrite faces
[MQOBJECT_RENDER_ALPHABLEND] Alpha blending
[MQOBJECT_RENDER_MULTILIGHT] Multiple lights
[MQOBJECT_RENDER_SHADOW] Show shadow
[MQOBJECT_RENDER_TEXTURE] Show textures (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR] Show vertex color (new in Rev4.59)
[MQOBJECT_RENDER_VERTEXCOLOR_POINT] Show points by vertex color (new in Rev4.30)
[MQOBJECT_RENDER_SCREEN] Specify a position of a vertex on a screen coordinate (new in Rev4.50)

(new in Rev4.02)

It cancels a force hiding for the specified item.


BOOL MQObject::AllocUserData(int userdata_id);

userdata_id
A object user data ID
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It allocates a memory area for an user data in the object.

It uses an user data ID created by MQDocument::CreateObjectUserData() for 'userdata_id'.

When an user data that is already allocated is specified, this function will return TRUE without performing anything.

Please do not allocate an user data until it is actually needed because it is necessary for a memory.


void MQObject::FreeUserData(int userdata_id);

userdata_id
An object user data ID

(new in Rev3.10)

It frees a memory area for an user data allocated by MQObject::AllocUserData().

Please free it immediately when it is not necessary any longer. A memory will be wasted if it continues allocating carelessly.


BOOL MQObject::GetUserData(int userdata_id, void *buffer);

userdata_id
An object user data ID
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It gets an user data for an object.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateObjectUserData().

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetUserData().


BOOL MQObject::GetUserDataPart(int userdata_id, int offset, int copy_bytes, void *buffer);

userdata_id
An object user data ID
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially gets an user data for an object.

An area begins from the offset is stored to the buffer.

A size of buffer must be equal to or larger than copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateObjectUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetUserData().


BOOL MQObject::SetUserData(int userdata_id, const void *buffer);

userdata_id
An object user data ID
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It sets an user data with the buffer.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateObjectUserData().

It will return FALSE when you specify an user data that has not been allocated yet.


BOOL MQObject::SetUserDataPart(int userdata_id, int offset, int copy_bytes, const void *buffer);

userdata_id
An object user data ID
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially sets an user data for an object.

A data in the buffer is copied to an area begins from the offset.

A size of buffer must be equal to or larger than copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateObjectUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet.


BOOL MQObject::AllocVertexUserData(int userdata_id);

userdata_id
A vertex user data ID
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It allocates a memory area for an user data in vertices.

It uses an user data ID created by MQDocument::CreateVertexUserData() for 'userdata_id'.

When an user data that is already allocated is specified, this function will return TRUE without performing anything.

Please do not allocate an user data until it is actually needed because it is necessary for a memory.


void MQObject::FreeVertexUserData(int userdata_id);

userdata_id
A vertex user data ID

(new in Rev3.10)

It frees a memory area for an user data allocated by MQObject::AllocVertexUserData().

Please free it immediately when it is not necessary any longer. A memory will be wasted if it continues allocating carelessly.


BOOL MQObject::GetVertexUserData(int userdata_id, void *buffer);

userdata_id
A vertex user data ID
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It gets an user data for a vertex.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateVertexUserData().

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetVertexUserData().


BOOL MQObject::GetVertexUserDataPart(int userdata_id, int vertex_start_index, int copy_vertex_num, int offset, int copy_bytes, void *buffer);

userdata_id
A vertex user data ID
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially gets an user data for a vertex (or vertices).

An area begins from the offset is stored to the buffer.

A size of buffer must be equal to or larger than copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateVertexUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetVertexUserData().


BOOL MQObject::SetVertexUserData(int userdata_id, const void *buffer);

userdata_id
A vertex user data ID
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It sets an user data with the buffer.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateVertexUserData().

It will return FALSE when you specify an user data that has not been allocated yet.


BOOL MQObject::SetVertexUserDataPart(int userdata_id, int vertex_start_index, int copy_vertex_num, int offset, int copy_bytes, const void *buffer);

userdata_id
A vertex user data ID
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially sets an user data for a vertex (or vertices).

A data in the buffer is copied to an area begins from the offset.

A size of buffer must be equal to or larger than copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateVertexUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet.


BOOL MQObject::AllocFaceUserData(int userdata_id);

userdata_id
A face user data ID
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It allocates a memory area for an user data in vertices.

It uses an user data ID created by MQDocument::CreateFaceUserData() for 'userdata_id'.

When an user data that is already allocated is specified, this function will return TRUE without performing anything.

Please do not allocate an user data until it is actually needed because it is necessary for a memory.


void MQObject::FreeFaceUserData(int userdata_id);

userdata_id
A face user data ID

(new in Rev3.10)

It frees a memory area for an user data allocated by MQObject::AllocFaceUserData().

Please free it immediately when it is not necessary any longer. A memory will be wasted if it continues allocating carelessly.


BOOL MQObject::GetFaceUserData(int userdata_id, void *buffer);

userdata_id
A face user data ID
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It gets an user data for a face.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateFaceUserData().

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetFaceUserData().


BOOL MQObject::GetFaceUserDataPart(int userdata_id, int face_start_index, int copy_face_num, int offset, int copy_bytes, void *buffer);

userdata_id
A face user data ID
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A number for storing an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially gets an user data for a face (or faces).

An area begins from the offset is stored to the buffer.

A size of buffer must be equal to or larger than copy_face_num*copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateFaceUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet. And the buffer are filled with 0 when you specify an user data that has not been set yet by MQObject::SetFaceUserData().


BOOL MQObject::SetFaceUserData(int userdata_id, const void *buffer);

userdata_id
A face user data ID
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It sets an user data with the buffer.

A size of buffer must be equal to or larger than a size specified in MQDocument::CreateFaceUserData().

It will return FALSE when you specify an user data that has not been allocated yet.


BOOL MQObject::SetFaceUserDataPart(int userdata_id, int face_start_index, int copy_face_num, int offset, int copy_bytes, const void *buffer);

userdata_id
A face user data ID
face_start_index
A start index of faces
copy_face_num
A number of faces from a start face
offset
An offset from a head of an user data
copy_bytes
A number of bytes to copy data
buffer
A buffer stores an user data
Return value
[TRUE] Succeeded
[FALSE] Failed

(new in Rev3.10)

It partially sets an user data for a face (or faces).

A data in the buffer is copied to an area begins from the offset.

A size of buffer must be equal to or larger than copy_face_num*copy_bytes. A whole user data, that is, a number of bytes specified in MQDocument::CreateFaceUserData() is copied when 0 is specified for copy_bytes.

It will return FALSE when you specify an user data that has not been allocated yet.