Drawing Vectors on the Screen

You can create an object that represents a vector drawn in the flight view, as a holographic image in flight. You may move it to a new location, make it appear or disappear, change its color, and label. This page describes how to do that.
VECDRAW(start, vec, color, label, scale, show, width, pointy)
VECDRAWARGS(start, vec, color, label, scale, show, width, pointy)

Both these two function names do the same thing. For historical reasons both names exist, but now they both do the same thing. They create a new vecdraw object that you can then manipulate to show things on the screen:

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

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

Vector arrows can also be created with dynamic positioning and color. To do this, instead of passing static values for the first three arguments of VECDRAW() or VECDRAWARGS(), you can pass a Delegate for any of them, which returns a value of the correct type. Here’s an example where the Start, Vec, and Color are all dynamically adjusted by anonymous delegates that kOS will frequently call for you as it draws the arrow:

// Small dynamically moving vecdraw example:
SET anArrow TO VECDRAW(
  { return (6-4*cos(100*time:seconds)) * up:vector. },
  { return (4*sin(100*time:seconds)) * up:vector.  },
  { return RGBA(1, 1, RANDOM(), 1). },
  "Jumping arrow!",
  1.0,
  TRUE,
  0.2,
  TRUE,
  TRUE
).
wait 20. // Give user time to see it in motion.
set anArrow:show to false. // Make it stop drawing.

In the above example, VECDRAW() detects that the first argument is a delegate, and it uses this information to decide to assign it into VecDraw:STARTUPDATER, instead of into VecDraw:START. Similarly it detects that the second argument is a delegate, so it assigns it into VecDraw:VECUPDATER instead of into VecDraw:VEC. And it does the same thing with the third argument, assigning it into VecDraw:COLORUPDATER, instead of VecDraw:COLOR.

All the parameters of the VECDRAW() and VECDRAWARGS() are optional. You can leave any of the lastmost parameters off and they will be given a default:

Set anArrow TO VECDRAW().

Causes it to have these defaults:

Defaults
Suffix Default
START V(0,0,0) (center of the ship is the origin)
VEC V(0,0,0) (no length, so nothing appears)
COLO[U]R White
LABEL Empty string “”
SCALE 1.0
SHOW false
WIDTH 0.2
POINTY true
WIPING true

Examples:

// Makes a red vecdraw at the origin, pointing 5 meters north,
// with defaults for the un-mentioned
// paramters LABEL, SCALE, SHOW, and WIDTH.
SET vd TO VECDRAW(V(0,0,0), 5*north:vector, red).

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().

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 scalar Scale VEC and WIDTH but not START
SHOW boolean True to enable display to screen
WIDTH scalar width of vector, default is 0.2
POINTY boolean Will the pointy hat be drawn
STARTUPDATER KosDelegate assigns a delegate to auto-update the START attribute.
VECUPDATER KosDelegate assigns a delegate to auto-update the VEC attribute.
VECTORUPDATER   Same as VECUPDATER
COLORUPDATER KosDelegate assigns a delegate to auto-update the COLOR attribute.
COLOURUPDATER   Same as COLORUPDATER
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. If you leave the VecDraw:WIPING suffix at its default value of True, then there will be a wipe effect such that the line will fade-in as it goes, only becoming this color at the endpoint tip.

(You can pass in an RGBA with an alpha value less than 1.0 if you would like the line to never be fully opaque even at the tip.)

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. Note the font size the label is displayed in gets stretched when you change the SCALE or the WIDTH values.

VecDraw:SCALE
Access:Get/Set
Type:scalar

Optional, defaults to 1.0. Scalar to multiply the VEC by, and the WIDTH, but not the START.

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.

VecDraw:WIDTH
Access:Get/Set
Type:scalar

Define the width of the drawn line, in meters. The deafult is 0.2 if left off. Note, this also causes the font of the label to be enlarged to match if set to a value larger than 0.2.

VecDraw:POINTY
Access:Get/Set
Type:boolean

(Defaults to True if left off.) Will this line be drawn with a pointy arrowhead “hat” on the tip to show which end is the start point and which is the end point? If this is false, then Vecdraw draws just a thick line, instead of an arrow.

VecDraw:WIPING
Access:Get/Set
Type:boolean

(Defaults to True if left off.) If true, this line will be drawn with a “wipe” effect that varies how transparent it is. At the start point it will be a more transparent version of the color you specified in VecDraw:COLOR. It will only become the full opacity you requested when it reaches the endpoint of the line. This effect is to help show the direction the arrow is going as it “fades in” to full opacity as it goes along.

If false, then the opacity of the line will not vary. It will draw the whole line at the exact color you specified in the in the VecDraw:COLOR SUFFIX. (Which can still be transparent if you use an RGBA() and provide the alpha value.)

VecDraw:STARTUPDATER
Access:Get/Set
Type:KosDelegate with no parameters, returning a Vector

This allows you to tell the VecDraw that you’d like it to update the START position of the vector regularly every update, according to your own scripted code.

You create a KosDelegate that takes no parameters, and returns a vector, which the system will automatically assign to the START suffix every update. Be aware that this system does eat into the instructions available per update, so if you make this delegate do too much work, it will slow down your script’s performance.

To make the system stop calling your delegate, set this suffix to the magic keyword DONOTHING.

Example:

// This example will bounce the arrow up and down over time for a few seconds,
// moving the location of the vector's start according to a sine wave over time:
set vd to vecdraw(v(0,0,0), ship:north:vector*5, green, "bouncing arrow", 1.0, true, 0.2).
print "Moving the arrow up and down for a few seconds.".
set vd:startupdater to { return ship:up:vector*3*sin(time:seconds*180). }.
wait 5.
print "Stopping the arrow movement.".
set vd:startupdater to DONOTHING.
wait 3.
print "Removing the arrow.".
set vd to 0.

New in version 1.1.0: scripted Delegate callbacks such as this did not exist prior to kOS version 1.1.0

VecDraw:VECUPDATER
Access:Get/Set
Type:KosDelegate with no parameters, returning a Vector

This allows you to tell the VecDraw that you’d like it to update the VEC suffix of the vector regularly every update, according to your own scripted code.

You create a KosDelegate that takes no parameters, and returns a vector, which the system will automatically assign to the VEC suffix every update. Be aware that this system does eat into the instructions available per update, so if you make this delegate do too much work, it will slow down your script’s performance.

To make the system stop calling your delegate, set this suffix to the magic keyword DONOTHING.

Example:

// This example will spin the arrow around in a circle by leaving the start
// where it is but moving the tip by trig functions:
set vd to vecdraw(v(0,0,0), v(5,0,0), green, "spinning arrow", 1.0, true, 0.2).
print "Moving the arrow in a circle for a few seconds.".
set vd:vecupdater to {
   return ship:up:vector*5*sin(time:seconds*180) + ship:north:vector*5*cos(time:seconds*180). }.
wait 5.
print "Stopping the arrow movement.".
set vd:vecupdater to DONOTHING.
wait 3.
print "Removing the arrow.".
set vd to 0.

New in version 1.1.0: scripted Delegate callbacks such as this did not exist prior to kOS version 1.1.0

VecDraw:VECTORUPDATER

This is just an alias for VecDraw:VECUPDATER.

VecDraw:COLORUPDATER
Access:Get/Set
Type:KosDelegate with no parameters, returning a Color

This allows you to tell the VecDraw that you’d like it to update the COLOR/COLOUR suffix of the vector regularly every update, according to your own scripted code.

You create a KosDelegate that takes no parameters, and returns a Color, which the system will automatically assign to the COLOR suffix every update. Be aware that this system does eat into the instructions available per update, so if you make this delegate do too much work, it will slow down your script’s performance.

To make the system stop calling your delegate, set this suffix to the magic keyword DONOTHING.

Example:

// This example will change how opaque the arrow is over time by changing
// the 'alpha' of its color:
set vd to vecdraw(v(0,0,0), ship:north:vector*5, green, "fading arrow", 1.0, true, 0.2).
print "Fading the arrow in and out for a few seconds.".
set vd:colorupdater to { return RGBA(0,1,0,sin(time:seconds*180)). }.
wait 5.
print "Stopping the color change.".
set vd:colorupdater to DONOTHING.
wait 3.
print "Removing the arrow.".
set vd to 0.

New in version 1.1.0: scripted Delegate callbacks such as this did not exist prior to kOS version 1.1.0

VecDraw:COLOURUPDATER

This is just an alias for VecDraw:COLORUPDATER.