Blitz3D+ Command Reference

TFormVector x#,y#,z#,source_entity,dest_entity

Parameters

x# - x component of the vector
y# - y component of the vector
z# - z component of the vector
source_entity - entity whose space the vector is given in, or 0 for world space
dest_entity - entity whose space to convert the vector into, or 0 for world space

Description

Converts a direction vector from one entity's coordinate space to another's.

A vector is a displacement - "one step right, two up, three forward" - rather than a place, so TFormVector applies rotation and scale but ignores the entities' positions. Use 0 for either entity to mean world space, and read the result with TFormedX, TFormedY and TFormedZ.

This is the tool for questions like "which way is this entity's forward, in world terms?" - TFormVector 0,0,1,entity,0 - which you can then feed into physics, or into moving another entity the same way. It is the same relationship PositionEntity and MoveEntity have: PositionEntity works with points, MoveEntity effectively adds a vector in entity space.

If the entities are scaled, the vector's length is scaled too. When you only care about direction, TFormNormal does the same job and returns a length-1 result.

See also: TFormPoint, TFormNormal, TFormedX, TFormedY, TFormedZ.

Example

; TFormVector Example
; -------------------

; TFormVector converts a DIRECTION from one coordinate space to
; another - like TFormPoint, but ignoring position. Here we ask:
; where would one 2-unit step 'forward' take the ship? The ghost
; marker shows the answer; Space actually takes the step.

Graphics3D 640,480
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,6,-8
RotateEntity camera,35,0,0

light=CreateLight()
RotateEntity light,45,45,0

; A ground plane for reference
ground=CreatePlane()
EntityColor ground,40,80,50
PositionEntity ground,0,-1,0

; The ship: a cone whose MESH is rotated so its nose points along +z
ship=CreateCone()
RotateMesh ship,90,0,0
EntityColor ship,255,180,60

; A ghost marker showing where a forward step would land
marker=CreateSphere()
ScaleEntity marker,0.2,0.2,0.2
EntityColor marker,120,220,255
EntityFX marker,1
EntityAlpha marker,0.6

While Not KeyDown(1)

    ; Left / Right steer the ship
    If KeyDown(203) Then TurnEntity ship,0,2,0
    If KeyDown(205) Then TurnEntity ship,0,-2,0

    ; The documented command: the ship's local 'forward' (0,0,2)
    ; expressed as a world-space direction
    TFormVector 0,0,2,ship,0
    PositionEntity marker,EntityX(ship)+TFormedX(),EntityY(ship)+TFormedY(),EntityZ(ship)+TFormedZ()

    ; Space takes the step - the ship lands exactly on the marker
    If KeyHit(57) Then MoveEntity ship,0,0,2

    RenderWorld

    Text 0,0,"Left/Right: steer   Space: step forward   Esc: exit"
    Text 0,20,"TFormVector 0,0,2,ship,0 = "+TFormedX()+", "+TFormedY()+", "+TFormedZ()
    Text 0,40,"The ghost marker sits one step ahead of the ship"

    Flip

Wend

End

Index