Blitz3D+ Command Reference

AddMorphTarget ( mesh,pose_mesh[,name$][,attributes] )

Parameters

mesh - destination mesh node that stores the captured target

pose_mesh - donor mesh with matching ordered surfaces, vertex counts, triangles and triangle index order

name$ (optional) - unique target name, compared without case; "" selects an unused "Morph N" name (default)

attributes (optional) - bit mask of captured attributes; zero and unknown bits are errors:
1: position (default)
2: normal
4: tangent XYZ

Description

Captures a reusable morph target from a donor mesh and returns its zero-based index.

The target stores donor CPU base attributes minus destination CPU base attributes in mesh-local coordinates. Both arguments address their own mesh node; children are not searched. Entity transforms, current weights, skin poses, materials and shader displacement are ignored. All data is copied, so the donor may be freed immediately.

Matching counts alone cannot establish semantic vertex correspondence. For a single surface, CopyMesh is a convenient donor. CopyMesh may merge multi-surface meshes that share materials; build a matching donor explicitly in that case. All surfaces and selected values are validated before capture. Invalid inputs, duplicate names or allocation failure leave the destination unchanged.

Position-only capture does not recalculate normals. Prepare donor normals with UpdateNormals before using bit 2. Tangent capture requires valid authored/generated tangents on both inputs, matching tangent handedness, and finite values. Tangent W is retained, never blended.

Definitions are shared by CopyEntity instances. Each copy starts the new slot at zero and retains its previous weights. Use SetMorphWeight to change a pose; finite negative and above-one weights are supported. Older animation keys and crossfades treat newly appended slots as zero.

Vertex queries and mesh collision continue to use CPU base vertices. Coordinate edits change the shared base while captured deltas remain offsets. Whole-mesh transforms and FlipMesh preserve target correspondence. Topology changes require ClearMorphTargets first. CopyMesh continues to produce independent static base geometry.

Capture is rejected while any entity sharing the destination geometry has LOD levels, or while the destination is referenced as another entity's LOD. Clear those LOD relationships before capture. Morph targets do not make geometry eligible for rigid LOD or planar receivers.

For a larger walkthrough, see the complete interactive captured-target sample.

Requires Extended mode.

See also: ClearMorphTargets, CountMorphTargets, FindMorphTarget, MorphWeight, SetMorphWeight.

Example

; Extended mode. Normal capture requires UpdateNormals on the donor.
; Tangent bit4 needs authored/generated tangents with matching handedness.
Graphics3D 800,500,0,2
SetBuffer BackBuffer()
camera=CreateCamera()
PositionEntity camera,0,0,-6
light=CreateLight()
RotateEntity light,30,20,0
base=CreateSphere(20)
pose=CopyMesh(base)
ScaleMesh pose,1,1.5,.65
UpdateNormals pose
target=AddMorphTarget(base,pose,"Stretch",3)
FreeEntity pose
EntityColor base,80,180,240
timer=CreateTimer(60)
weight#=0
While Not KeyHit(1)
    WaitTimer timer
    weight=weight+(KeyDown(205)-KeyDown(203))*.025
    SetMorphWeight base,target,weight
    RenderWorld
    Text 10,10,"Left / Right: weight "+weight+"    Escape: exit"
    Text 10,35,"The captured donor was freed. Position and normal deltas remain available."
    Text 10,455,"CPU vertex queries / collision use the base sphere. CopyEntity shares base geometry."
    Flip
Wend
FreeTimer timer
FreeEntity base
FreeEntity light
FreeEntity camera
EndGraphics
End

Index