Enhanced Object Script Editor



This screen can be reached from the Display Object Properties box for Enhanced display objects.


Enhanced display objects are an advanced feature that enable the possibility of many advanced, unique, or one-off displays. While it should be easy to add existing Enhanced object styles to your project, creating new ones or modifying existing scripts will require suitable programming skill and effort. For displays that are much easier to customize, please see the many other display object types, such as gauges, bar / level graphs, 2D graphs, text data, etc.

Please first utilize this documentation and other resources before contacting RaceRender LLC for programming / scripting questions or assistance, as we unfortunately do not have the resources to teach computer programming, or to analyze or debug everyone's code. This scripting language was designed with common C-style syntax, so that the many knowledge and education resources for C and certain other programming languages could largely apply here as well.


Introduction
Although RaceRender offers many easily-customizable display objects to visualize data in a variety of different ways, there is sometimes a desire to take it even further and create displays with unique characteristics that don�t fit into the scope of a traditional gauge or graph. For these cases, RaceRender offers Enhanced display objects, which allow advanced technical users to write their own code to control how a display is drawn and animated. Once completed, the result can then be easily exported as a .RRO object file and shared with other RaceRender users, so that even non-technical users can benefit from it too.

Writing or modifying code for an Enhanced display object does require some programming experience, so this advanced level of customization is not for everyone. That said, it intends to be a relatively simple functional scripting language, to hopefully accommodate as many technically-inclined users as possible, while still offering powerful functionality. It is based on a subset of C-style syntax that should be familiar to users who have experience with languages like C, C++, C#, Objective-C, JavaScript, Java, or PHP. It should most closely relate to the C programming language.

Please note that while this can be a powerful tool, it is not meant to be a complete programming language. The scripts are intentionally limited to the confines of its display object, and only the specific functions, statements, and operators listed here are supported. Therefore, trying to use source code copied from other programs, or other languages, will probably not work without some modification.

For general programming questions and help, there are many resources available on the Internet, and in particular, those which relate to the basic syntax of the C programming language may be most relevant. Keep in mind the points listed in this documentation, as there are some key differences and deliberate limitations. If you find that your code or a certain statement isn�t working quite as expected, you might try rewriting in another way, to see if that gives the desired results. As with any language, there may be a few unique characteristics here that cause different behavior, some of which are explained below.


Key Points
  • The Background Script is run once to generate the static object background image. Ideally, it should handle the drawing of all elements that will not change from frame to frame.

  • The Foreground Script is run for each video frame, and is meant to handle drawing dynamic content that can change based on the current DataValue, SampleTime, and/or DisplayTime. Anything it draws will be placed on top of the graphics generated by the background script. To avoid unnecessary performance costs, be sure to use the background script to draw as many of the static display elements as possible.

  • The scripting language is intentionally simple, and is limited to the capabilities and functions described here. It does not intend to be directly compatible with any specific programming or scripting language, but is meant to be generally similar to common languages that are based on C-style syntax.

  • It is proper for statements to be explicitly terminated with a semi-colon ; at the end, but this is not mandatory here
    • The end of a line will also be interpreted as the end of the statement, unless it�s between parenthesis ( )

  • Supports code comments
    • // Single line comment
    • /* Multi-line comment block */
    • You can use these to add your own comment text to the code
    • These can also be helpful for temporarily disabling certain statements when developing your code

  • Simplified data type: All numerical values are treated as floating point (64-bit precision)
    • The logic evaluations should account for most floating point imprecision (i.e. 0.99999999 == 1.0)
      • Due to normal floating point error, this can not accommodate all possible cases (use the round() function)
    • If you need it to act like an integer, use the round(), trunc(), floor() or ceil() functions

  • Hexadecimal values are accepted in 0x12345678 format
    • Colors are defined as a 24-bit number, such as 0xF08040 (0xF0 Red, 0x80 Green, 0x40 Blue)

  • ASCII character values are accepted when enclosed in single-quotes, such as 'A'
    • The character's ASCII value is stored as a number
    • Only a single character may be used
    • Escape sequences are not supported
    • This is currently only useful for the DrawChar() function

  • ASCII strings are accepted when enclosed in double-quotes, such as "Abc123"
    • Up to 63 characters may be used
    • Escape sequences are not supported
    • This is useful for functions like DrawText(), GetDataIndex(), and Print()
    • Strings are not allowed for functions or operations that expect a numerical value

  • Variables are automatically defined when you first use them
    • A maximum of 128 variables may be used (total between background and foreground scripts)
    • Variable names must be entirely ASCII letters or numbers ('A'-'Z', 'a'-'z', '0'-'9', or '_')
    • Variable names cannot start with a number
    • Variable names cannot match any function name, statement name, or reserved name
    • Variable names are not case sensitive ("MyVar" is the same as "myvar")
    • There are no arrays

  • Variables set in the background script will also be available to the foreground script
    • Be default, any changes that the foreground script makes to these will be reverted after each run
    • The Persistent Script Variables option will retain the values set by the foreground script, but should be used with care, as it can lead to some odd behavior.

  • Supports common numeric operators:
    • Variable Setting:  =
    • Logic Evaluations:  ==   !=   >=   <=   >   <
    • Logic AND / OR:  &&   ||
    • Logic NOT:  !
    • Unary plus and minus:  +   -
    • Arithmetic:  +   -   *   /   %
    • Arithmetic Assignment:  +=   -=   *=   /=   %=
    • Bitwise:  ^
    • Bitwise Assignment:  ^=
    • (Other bitwise operators are not supported)

  • Supports common string operators:
    • Variable Setting:  =
    • Comparison:  ==   !=
    • Concatenation:  +
    • Concatenation Assignment:  +=

  • Operations that mix numeric and string types are not allowed
    • Tip: Use FormatNumber() to convert a numeric value into a string

    • Invalid: 1000 + "1"
    • Valid (numeric 1001): 1000 + 1
    • Valid (string "10001"): FormatNumber(1000, 0) + "1"

    • Invalid: 1000 + " MPH"
    • Valid (string "1000 MPH"): FormatNumber(1000, 0) + " MPH"

  • if, else, and return statements are supported
    • else if is supported, but must always be written together as "else if", with only a space in between (no line breaks).
    • Nested if statements must always be inside { } brackets:
      • if(ConditionA)
      {
          if(ConditionB)
              print(456);
      }

  • Function and statement names are not case sensitive (�DrawDot()� is the same as �drawdot()�)

  • There is no capability for user-defined functions

  • Loops are not supported at this time


Available Data Values / Constants (read-only)
  • Data Values

    • DataMin: Minimum data value, as set by the user or as measured (if automatic)
    • DataMinAuto: Set to true if DataMin was the result of automatic measurement, or false if DataMin came from the user
    • DataMax: Maximum data value, as set by the user or as measured (if automatic)
    • DataMaxAuto: Set to true if DataMax was the result of automatic measurement, or false if DataMax came from the user
    • DataRange: Equal to DataMax - DataMin
    • DataTrigger: Trigger activation level set by the user (when enabled; controls IsTriggered)
    • DataTriggerFactor: Like DataFactor, but for the DataTrigger value (when enabled)

    • Foreground Script Only:
      • DataValue: Current sample data value from the input file
      • DataFactor: DataValue expressed in a range from 0.0 to 1.0, based on DataMin and DataMax
      • IsTriggered: Set to 1 if DataValue >= DataTrigger (when enabled)
      • SampleTime: Current time (in seconds) in the input file
      • FrameInterval: Duration/Interval (in seconds) of frame at the current target frame rate
      • DisplayTime: Current time (in seconds) relative to the start of this display object (resets to zero upon each new timeline segment)

  • Drawing Canvas Values

    • SizeX: Rendering canvas width
    • SizeY: Rendering canvas height
    • CenterX: Horizontal center coordinate in canvas
    • CenterY: Vertical center coordinate in canvas

  • User Parameter Values

    • ColorA: 1st user-controlled color value (when enabled)
    • ColorB through ColorG
    • ColorH: 8th user-controlled color value (when enabled)

  • String Values

    • SpeedUnit: Current project's preferred speed unit ("MPH", "km/h", "knots", "m/s")
    • InputName: Current input's name / label
    • LocName: Location name, based on the input's starting coordinates (if available)
      Note: The functionality of this may change in the future

  • General Constants

    • True: Equivalent to 1
    • False: Equivalent to 0

    • Filled: Draws a solid shape when specified as the Thickness parameter for Circles, Rectangles, and Polygons

    • Colors:
      • White
      • Gray
      • Black
      • Red
      • Green
      • Blue
      • Yellow
      • Orange
      • Brown
      • Cyan
      • Magenta

      • Transparent - special case used for SetTextOutline()
      • Invisible - same as Transparent

    • Text Alignment: (for use with DrawNumber(), DrawTime(), DrawChar(), and DrawText())
      • AlignH_Left - Horizontal align left
      • AlignH_Center - Horizontal align center
      • AlignH_Right - Horizontal align right

    • Data Field Types: (for use with GetDataValue())
      • DFT_PosX - X Position (Longitude if GPS coordinates)
      • DFT_PosY - Y Position (Latitude if GPS coordinates)
      • DFT_PosZ - Z Position (Altitude, in meters)
      • DFT_Speed - Speed (unit depends on user setting)
      • DFT_Heading - Heading (0.0 - 359.9 degrees)
      • DFT_GForceX - X Acceleration (G's)
      • DFT_GForceY - Y Acceleration (G's)
      • DFT_Throttle - Throttle Position (typically 0-100%; depends on input data file)
      • DFT_Brake - Brake Switch or Position (depends on input data file)
      • DFT_RPM - Engine RPM
      • DFT_Gear - Transmission Gear number
      • DFT_AirFuel - Air/Fuel Ratio or Lambda (depends on input data file)
      • DFT_Power - Engine Power Output (typically HP or kW; depends on input data file)
      • DFT_Torque - Engine Torque Output (typically ft-lbs or Nm; depends on input data file)


Available Functions
Drawing
Coordinates, Size, and Thickness are rounded to whole integers (i.e. 1.7 is treated as 2, 1.3 as 1).
For Circles, Rectangles, and Polygons, the Thickness parameter may be set to Filled to draw a solid shape.
  • Text
      • Set the Alignment parameter to a value like AlignH_Left (see options further above)
      (X,Y is top left corner by default)

    • SetTextOutline(Color)
      Sets the outline color used for for DrawNumber(), DrawTime(), DrawChar(), and DrawText().
      Call SetTextOutline(Transparent) to disable it.

    • DrawNumber(Value, Decimals, X, Y, Color, Size, Alignment)
      Draws Value as a number at X, Y
    • DrawTime(Value, Decimals, X, Y, Color, Size, Alignment, Compact)
      Draws Value (number of seconds) as a formatted time at X, Y
      Compact 0 = Always Show Hours, 1 = Minutes, 2 = Seconds
    • DrawChar(CharValue, X, Y, Color, Size, Alignment)
      Draws a character at X, Y. Note: single character only, not a string
    • DrawText(String, X, Y, Color, Size, Alignment)
      Draws a text string at X, Y

  • Lines & Shapes
    • DrawDot(X, Y, Color, Size)
      Draws a dot at X, Y
    • DrawDotGradient(X, Y, ColorA, ColorB, Size)
      Draws a dot at X, Y with gradient coloring
    • DrawDotGradientRGB(X, Y, ColorA, ColorB, Size)
      Draws a dot at X, Y with gradient coloring (RGB blending for brighter colors)
    • DrawSquare(X, Y, Color, Size)
      Draws a filled square at X, Y
    • DrawLine(X1, Y1, X2, Y2, Color, Thickness)
      Draws a line from X1, Y1 to X2, Y2
    • DrawLineGradient(X1, Y1, X2, Y2, ColorA, ColorB, Thickness)
      Draws a line from X1, Y1 to X2, Y2, with gradient coloring
    • DrawLineGradientRGB(X1, Y1, X2, Y2, ColorA, ColorB, Thickness)
      Draws a line from X1, Y1 to X2, Y2, with gradient coloring (RGB blending for brighter colors)
    • DrawLineFlat(X1, Y1, X2, Y2, Color, Thickness)
      Draws a line from X1, Y1 to X2, Y2, with flat ends
    • DrawCircle(X, Y, Radius, Color, Thickness)
      Draws a circle with a center at X, Y. Thickness may be set to Filled
    • DrawCurve(X1, Y1, ControlX, ControlY, X2, Y2, ProgressLimit, ColorA, ColorB, ThicknessA, ThicknessB)
      Draws a quadratic Bezier curve from X1,Y1 to X2,Y2 based on specified control point, with optional thickness tapering and gradient-coloring
      ProgressLimit should be between 0.0 and 1.0; Use 1.0 to draw the entire curve.
    • DrawCurveRGB(X1, Y1, ControlX, ControlY, X2, Y2, ProgressLimit, ColorA, ColorB, ThicknessA, ThicknessB)
      Draws a quadratic Bezier curve from X1,Y1 to X2,Y2 based on specified control point, with optional thickness tapering and gradient-coloring (RGB blending for brighter colors)
      ProgressLimit should be between 0.0 and 1.0; Use 1.0 to draw the entire curve.
    • DrawRect(X1, Y1, X2, Y2, Color, Thickness)
      Draws a rectangle from X1, Y1 to X2, Y2. Thickness may be set to Filled
    • DrawRRect(X1, Y1, X2, Y2, Color, Thickness)
      Draws a rounded-rectangle from X1, Y1 to X2, Y2. Thickness may be set to Filled
    • DrawORect(X1, Y1, X2, Y2, Color, Thickness)
      Draws an oval-shaped rectangle from X1, Y1 to X2, Y2. Thickness may be set to Filled
    • DrawPoly3(X1, Y1, X2, Y2, X3, Y3, Color, Thickness)
      Draws a 3-point polygon from X1, Y1 to X2, Y2 to X3, Y3. Thickness may be set to Filled
    • DrawPoly4(X1, Y1, X2, Y2, X3, Y3, X4, Y4, Color, Thickness)
      Draws a 4-point polygon from X1, Y1 to X2, Y2 to X3, Y3 to X4, Y4. Thickness may be set to Filled

  • Color Blending
    • BlendColors(Color1, Color2, Amount)
      Returns color blended from Color1 to Color2 by Amount (0.0 to 1.0)
    • BlendColorsRGB(Color1, Color2, Amount)
      Returns color RGB-blended from Color1 to Color2 by Amount (0.0 to 1.0). This tends to result in brighter colors than the BlendColors() function.

Data Input: General
  • GetDataIndex(DataFieldName)
    Gets current data field index for the given data channel name (text string). These indexes are dynamic, based on the input data file.
    Important: This can reduce performance if used in the Foreground script. Instead, use it to set a variable in the Background script, and then use that variable with GetDataValue() in the Foreground script.

  • GetDataValue(DataFieldIndex)
    Gets current data value for the specified data channel. See DFT_* values for available options, or obtain an index for a specific named channel using GetDataIndex().

Data Input: Lap Numbers & Times
  • GetLapTime(LapNum)
    Gets the completed lap time (in seconds) for the given lap number
  • GetCurLapNum()
    Gets the current lap number
  • GetCurLapTime()
    Gets the current running lap time (in seconds)
  • GetBestLapNum()
    Gets the overall best lap number
  • GetBestLapTime()
    Gets the overall best lap time (in seconds)
  • GetCurBestLapNum()
    Gets the current best lap number
  • GetCurBestLapTime()
    Gets the current best lap time (in seconds)
  • GetPrevBestLapNum()
    Gets the best lap number as of the previous lap
  • GetPrevBestLapTime()
    Gets the best lap time (in seconds) as of the previous lap

General
  • FormatNumber(Value, Decimals)
    Returns a string from a numeric value, shown to the specified number of decimal places.
  • FormatHeading(Value)
    Returns a directional heading string from a numeric heading value (0-360 degrees).
  • strlen(String)
    Returns the number of characters in a string.
  • substr(String, StartPos, Length)
    Returns a substring from within a string, based on StartPos (index of first character; starts at zero) and Length (number of characters).
    Returns a blank string if StartPos is invalid. Returns all characters after StartPos if Length is <0 or larger than input string length.
  • ToUpper(String)
    Converts a string to uppercase.
  • ToLower(String)
    Converts a string to lowercase.
  • trim(String)
    Trims whitespace off of the start and end of a string.
  • chr(Value)
    Converts an ASCII character code value into a text character.
  • asc(Character)
    Converts a text character into its an ASCII character code value.

  • Strobe(Interval)
    Alternates between true and false (1 and 0 integers) based on Interval (seconds); useful for making things flash.
  • Print(Value, ...)
    Writes one or more parameter values (numeric or string) to the Output Messages log

Math
  • abs(Value)
    Absolute: Removes negative sign, if applicable (-1.5 becomes 1.5, 1.7 remains 1.7)
  • ceil(Value)
    Ceiling: Rounds Value up to the next higher integer (1.3 becomes 2.0, -1.3 becomes -1.0)
  • floor(Value)
    Floor: Rounds Value down to the lower integer (1.7 becomes 1.0, -1.7 becomes -2.0)
  • max(ValueA, ValueB)
    Maximum: Returns the greater of ValueA and ValueB
  • min(ValueA, ValueB)
    Minimum: Returns the lesser of ValueA and ValueB
  • pow(Base, Exponent)
    Power: Raise Base to the specified Exponent
  • round(Value, Decimals)
    Round: Rounds Value to number of decimal places; if 0, then the nearest integer (1.6 becomes 2.0, 1.4 becomes 1.0)
  • sqrt(Value)
    Square Root
  • trunc(Value)
    Truncate: Discards the decimal component of Value to make it an integer (1.7 becomes 1.0, -1.7 becomes -1.0)

  • sin(Degrees)
    Sine
  • cos(Degrees)
    Cosine
  • tan(Degrees)
    Tangent
  • asin(Value)
    Arc sine of Value, in degrees
  • acos(Value)
    Arc cosine of Value, in degrees
  • atan(Value)
    Arc tangent of Value, in degrees
  • atan2(X, Y)
    Arc tangent of Y/X, in degrees
  • hypot(X, Y)
    Hypotenuse of triangle with sides of X and Y length. Square root of (X2 + Y2)