diff --git a/doc/source/structures/misc/vecdraw.rst b/doc/source/structures/misc/vecdraw.rst index d05311a0a..583137f73 100644 --- a/doc/source/structures/misc/vecdraw.rst +++ b/doc/source/structures/misc/vecdraw.rst @@ -3,62 +3,77 @@ Drawing Vectors on the Screen ============================= -.. function:: VECDRAW() or VECDRAWARGS() + 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. - Build the suffix fields one at a time using the :struct:`VecDraw` empty construction function. This creates an empty :struct:`VecDraw` with nothing populated yet. You have to follow it up with calls to the suffixes as shown here:: +.. function:: VECDRAW(start, vec, color, label, scale, show, width) +.. function:: VECDRAWARGS(start, vec, color, label, scale, show, width) - 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. - - -.. function:: VECDRAW(start, vec, color, label, scale, show) or VECDRAWARGS(start, vec, color, label, scale, show) - - This variant builds the :struct:`VecDraw` all at once. It lets you specify all of the attributes in a list of arguments at once:: + 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?", - 5.0, - TRUE + 1.0, + TRUE, + 0.2 ). - // 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 + 1.0, + TRUE, + 0.2 ). -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. :struct:`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:: + 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: + + .. list-table:: Defaults + :header-rows: 1 + :widths: 1 3 - 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 ). + * - Suffix + - Default -To make a :struct:`VecDraw` disappear, you can either set its :attr:`VecDraw:SHOW` to false or just UNSET the variable, or re-assign it. An example using :struct:`VecDraw` can be seen in the documentation for :func:`POSITIONAT()`. + * - :attr:`START` + - V(0,0,0) (center of the ship is the origin) + * - :attr:`VEC` + - V(0,0,0) (no length, so nothing appears) + * - :attr:`COLO[U]R` + - White + * - :attr:`LABEL` + - Empty string "" + * - :attr:`SCALE` + - 1.0 + * - :attr:`SHOW` + - false + * - :attr:`WIDTH` + - 0.2 + Examples:: -.. 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. + // 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 :struct:`VecDraw` disappear, you can either set its :attr:`VecDraw:SHOW` to false or just UNSET the variable, or re-assign it. An example using :struct:`VecDraw` can be seen in the documentation for :func:`POSITIONAT()`. .. _clearvecdraws: @@ -105,11 +120,14 @@ To make a :struct:`VecDraw` disappear, you can either set its :attr:`VecDraw:SHO - string - Text to show next to vector * - :attr:`SCALE` - - integer - - Scale :attr:`START` and :attr:`VEC` + - scalar number + - Scale :attr:`VEC` and :attr:`WIDTH` but not :attr:`START` * - :attr:`SHOW` - boolean - - Draw vector to screen + - True to enable display to screen + * - :attr:`WIDTH` + - scalar number + - width of vector, default is 0.2 @@ -148,13 +166,22 @@ To make a :struct:`VecDraw` disappear, you can either set its :attr:`VecDraw:SHO :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 :attr:`SCALE` or the :attr:`WIDTH` values. .. attribute:: VecDraw:SCALE :access: Get/Set - :type: integer + :type: Scalar number + + Optional, defaults to 1.0. Scalar to multiply the VEC by, and the WIDTH, + but not the START. - Optional, defauls to 1. Scalar to multiply by both the START and the VEC + .. versionchanged:: 0.19.0 + + In previous versions, this also moved the start location, but most + users found that useless and confusing and that has been + changed as described above. .. attribute:: VecDraw:SHOW @@ -163,4 +190,15 @@ To make a :struct:`VecDraw` disappear, you can either set its :attr:`VecDraw:SHO Set to true to make the arrow appear, false to hide it. Defaults to false until you're ready to set it to true. +.. attribute:: VecDraw:WIDTH + + :access: Get/Set + :type: Scalar number + + 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. + + .. versionadded:: 0.19.0 + This parameter didn't exist before kOS 0.19.0. diff --git a/src/kOS/Function/Suffixed.cs b/src/kOS/Function/Suffixed.cs index 965e0bc90..82170cef9 100644 --- a/src/kOS/Function/Suffixed.cs +++ b/src/kOS/Function/Suffixed.cs @@ -304,45 +304,28 @@ public class FunctionVecDrawNull : FunctionBase public override void Execute(SharedObjects shared) { int argc = CountRemainingArgs(shared); - // If I was called with arguments, then run the version of the constructor that takes args - if (argc == 6) - { - bool show = Convert.ToBoolean(PopValueAssert(shared)); - double scale = GetDouble(PopValueAssert(shared)); - string str = PopValueAssert(shared).ToString(); - RgbaColor rgba = GetRgba(PopValueAssert(shared)); - Vector vec = GetVector(PopValueAssert(shared)); - Vector start = GetVector(PopValueAssert(shared)); - AssertArgBottomAndConsume(shared); - DoExecuteWork(shared, start, vec, rgba, str, scale, show); - } - else if (argc == 0) - { - AssertArgBottomAndConsume(shared); // no args - DoExecuteWork(shared); // default constructor: - } - else - { - throw new KOSArgumentMismatchException("Vecdraw() expected either 0 or 6 arguments passed, but got " + argc +" instead."); - } + + // Handle the var args that might be passed in, or give defaults if fewer args: + double width = (argc >= 7) ? GetDouble(PopValueAssert(shared)) : 0.2; + bool show = (argc >= 6) ? Convert.ToBoolean(PopValueAssert(shared)) : false; + double scale = (argc >= 5) ? GetDouble(PopValueAssert(shared)) : 1.0; + string str = (argc >= 4) ? PopValueAssert(shared).ToString() : ""; + RgbaColor rgba = (argc >= 3) ? GetRgba(PopValueAssert(shared)) : new RgbaColor(1.0f, 1.0f, 1.0f); + Vector vec = (argc >= 2) ? GetVector(PopValueAssert(shared)) : new Vector(1.0, 0.0, 0.0); + Vector start = (argc >= 1) ? GetVector(PopValueAssert(shared)) : new Vector(0.0, 0.0, 0.0); + AssertArgBottomAndConsume(shared); + DoExecuteWork(shared, start, vec, rgba, str, scale, show, width); } - public void DoExecuteWork(SharedObjects shared) - { - var vRend = new VectorRenderer( shared.UpdateHandler, shared ); - vRend.SetShow( false ); - - ReturnValue = vRend; - } - - public void DoExecuteWork(SharedObjects shared, Vector start, Vector vec, RgbaColor rgba, string str, double scale, bool show) + public void DoExecuteWork(SharedObjects shared, Vector start, Vector vec, RgbaColor rgba, string str, double scale, bool show, double width) { var vRend = new VectorRenderer( shared.UpdateHandler, shared ) { Vector = vec, Start = start, Color = rgba, - Scale = scale + Scale = scale, + Width = width }; vRend.SetLabel( str ); vRend.SetShow( show ); diff --git a/src/kOS/Suffixed/VectorRenderer.cs b/src/kOS/Suffixed/VectorRenderer.cs index 521c0fc10..7b130ec4f 100644 --- a/src/kOS/Suffixed/VectorRenderer.cs +++ b/src/kOS/Suffixed/VectorRenderer.cs @@ -244,8 +244,7 @@ public void SetShow( bool newShowVal ) // Font lblFont = (Font)Resources.Load( "Arial", typeof(Font) ); // SafeHouse.Logger.Log( "lblFont is " + (lblFont == null ? "null" : "not null") ); // _label.font = lblFont; - - label.fontSize = 12; + label.text = labelStr; label.anchor = TextAnchor.MiddleCenter; @@ -294,6 +293,7 @@ public void SetLabel( string newVal ) { labelStr = newVal; if (label != null) label.text = labelStr; + RenderPointCoords(); } public void RenderValues() @@ -325,18 +325,14 @@ public void RenderPointCoords() mapWidthMult = Math.Max( camLookVec.magnitude, 100.0f ) / 100.0f; } - Vector3d point1 = mapLengthMult * Scale * Start; - Vector3d point2 = mapLengthMult * Scale * (Start+0.95*Vector); - Vector3d point3 = mapLengthMult * Scale * (Start+Vector); + Vector3d point1 = mapLengthMult * Start; + Vector3d point2 = mapLengthMult * (Start + (Scale * 0.95 * Vector)); + Vector3d point3 = mapLengthMult * (Start + (Scale * Vector)); - if (Width <= 0) // User didn't pick a valid width. Use dynamic calculation. - { - useWidth = (float) (0.2*mapWidthMult); - } - else // User did pick a width to override the dynamic calculations. - { - useWidth = (float)Width; - } + label.fontSize = (int) (12.0 * (Width/0.2) * Scale); + + useWidth = (float) (Width * Scale * mapWidthMult); + // Position the arrow line: line.SetVertexCount( 2 );