Drawing Vectors on the Screen¶

VECDRAW() or VECDRAWARGS()¶

Build the suffix fields one at a time using the VecDraw empty construction function. This creates an empty VecDraw with nothing populated yet. You have to follow it up with calls to the suffixes as shown here:

SET anArrow TO VECDRAW().
SET anArrow:VEC TO V(a,b,c).
SET anArrow:SHOW TO true.
// At this point you have done the minimal necessary to make the arrow appear
// and it shows up on the scren immediately.

// Further options can also be set:
SET anArrow:START TO V(0,0,0).
SET anArrow:COLOR TO RGB(1,0,0).
SET anArrow:LABEL TO "See the arrow?".
SET anArrow:SCALE TO 5.0.

VECDRAW(start, vec, color, label, scale, show) or VECDRAWARGS(start, vec, color, label, scale, show)

This variant builds the VecDraw all at once. It lets you specify all of the attributes in a list of arguments at once:

SET anArrow TO VECDRAW(
      V(0,0,0),
      V(a,b,c),
      RGB(1,0,0),
      "See the arrow?",
      5.0,
      TRUE
    ).

// Saying VECDRAWARGS gives the same exact result:
SET anArrow TO VECDRAWARGS(
      V(0,0,0),
      V(a,b,c),
      RGB(1,0,0),
      "See the arrow?",
      5.0,
      TRUE
    ).

The above two examples make the same thing. The arrow should be visible on both the map view and the in-flight view, but on the map view it will have to be a long arrow to be visible. VecDraw‘s do not auto-update for changes in the vector like a LOCK would, but if you repeatedly SET the :VEC suffix in a loop, it will adjust the arrow picture to match as you do so:

set xAxis to VECDRAWARGS( V(0,0,0), V(1,0,0), RGB(1.0,0.5,0.5), "X axis", 5, TRUE ).
set yAxis to VECDRAWARGS( V(0,0,0), V(0,1,0), RGB(0.5,1.0,0.5), "Y axis", 5, TRUE ).
set zAxis to VECDRAWARGS( V(0,0,0), V(0,0,1), RGB(0.5,0.5,1.0), "Z axis", 5, TRUE ).

To make a VecDraw disappear, you can either set its VecDraw:SHOW to false or just UNSET the variable, or re-assign it. An example using VecDraw can be seen in the documentation for POSITIONAT().

Note

Historical note: Once upon a time VECDRAW() took zero arguments, and VECDRAWARGS() took the 6 arguments. This was before we added the ability to have varying numbers of arguments for built-in functions. Now that varying arguments exist, both names have become synonyms for the same thing, for backward compatibility. You can use them interchangably.

CLEARVECDRAWS()¶: Sets all visible vecdraws to invisible, everywhere in this kOS CPU. This is useful if you have lost track of the handles to them and can’t turn them off one by one, or if you don’t have the variable scopes present anymore to access the variables that hold them. The system does attempt to clear any vecdraws that go “out of scope”, however the “closures” that keep local variables alive for LOCK statements and for other reasons can keep them from every truely going away in some circumstances. To make the arrow drawings all go away, just call CLEARVECDRAWS() and it will have the same effect as if you had done SET varname:show to FALSE for all vecdraw varnames in the entire system.

structure VecDraw¶

This is a structure that allows you to make a drawing of a vector on the screen in map view or in flight view.

Members¶
Suffix	Type	Description
`START`	`Vector`	Start position of the vector
`VEC`	`Vector`	The vector to draw
`COLOR`	Color	Color of the vector
`COLOUR`		Same as `COLOR`
`LABEL`	string	Text to show next to vector
`SCALE`	integer	Scale `START` and `VEC`
`SHOW`	boolean	Draw vector to screen

VecDraw:START¶

Access:	Get/Set
Type:	`Vector`

Optional, defaults to V(0,0,0) - position of the tail of the vector to draw in SHIP-RAW coords. V(0,0,0) means the ship Center of Mass.

VecDraw:VEC¶

Access:	Get/Set
Type:	`Vector`

Mandatory - The vector to draw, SHIP-RAW Coords.

VecDraw:COLOR¶

Access:	Get/Set
Type:	Color

Optional, defaults to white. This is the color to draw the vector. There is a hard-coded fade effect where the tail is a bit more transparent than the head.

VecDraw:COLOUR¶

Access:	Get/Set
Type:	Color

Alias for VecDraw:COLOR

VecDraw:LABEL¶

Access:	Get/Set
Type:	string

Optional, defaults to “”. Text to show on-screen at the midpoint of the vector.

VecDraw:SCALE¶

Access:	Get/Set
Type:	integer

Optional, defauls to 1. Scalar to multiply by both the START and the VEC

VecDraw:SHOW¶

Access:	Get/Set
Type:	boolean

Set to true to make the arrow appear, false to hide it. Defaults to false until you’re ready to set it to true.