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