|
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, time 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 and/or SampleTime. 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
- 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(), 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'
- This is currently only useful for the DrawChar() function
- 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 '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
- Any changes that the foreground script makes to these will be reverted after each run
- Supports common operators:
- Variable Setting: =
- Logic Evaluations: == != >= <= > <
- Logic AND / OR: && ||
- Logic NOT: !
- Unary plus and minus: + -
- Arithmetic: + - * / %
- Arithmetic Assignment: += -= *= /= %=
- (Bitwise operators are not supported)
- if, else, and return statements are supported
- else if is not implemented at this time. Use { } brackets instead:
if(ConditionA)
print(123);
else
{
if(ConditionB)
print(456);
}
- Nested if statements must 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 (read-only)
- 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
- SizeX: Rendering canvas width
- SizeY: Rendering canvas height
- CenterX: Horizontal center coordinate in canvas
- CenterY: Vertical center coordinate in canvas
- ColorA: 1st user-controlled color value (when enabled)
- ColorB through ColorG
- ColorH: 8th user-controlled color value (when enabled)
- True: Equivalent to 1
- False: Equivalent to 0
- Filled: Draws a filled shape when specified as the Thickness parameter for Circles, Rectangles, and Polygons
- Colors:
- White
- Gray
- Black
- Red
- Green
- Blue
- Yellow
- Orange
- Brown
- Cyan
- Magenta
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 filled shape.
- Alignment parameter values for DrawNumber(), DrawTime(), and DrawDot():
(X,Y is top left corner by default)
- 1 = Horizontal align center
- 2 = Horizontal align right
- 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
- 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
- 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
- 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
- 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
- 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 File
- 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
- Strobe(Interval)
Alternates between 1 and 0 based on Interval (seconds); useful for making things flash.
- Print(Value, ...)
Writes Value, and any additional parameters, to the Output Messages log
Math
- min(ValueA, ValueB)
Minimum: Returns the lesser of ValueA and ValueB
- max(ValueA, ValueB)
Maximum: Returns the greater of ValueA and ValueB
- 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)
- floor(Value)
Floor: Moves Value down to the lower integer (1.7 becomes 1.0)
- ceil(Value)
Ceiling: Moves Value up to the next higher integer (1.3 becomes 2.0)
- abs(Value)
Absolute: Removes negative sign, if applicable (-1.5 becomes 1.5, 1.7 remains 1.7)
- sqrt(Value)
Square Root
- sin(Degrees)
Sine
- cos(Degrees)
Cosine
- tan(Degrees)
Tangent
|