Effects Are Webpages
Effects in SignalRGB, known as Lightscripts, are essentially webpages that interact with the SignalRGB API, and they must adhere to some simple rules to function properly. Every Lightscript requires three essential HTML tags: <head>, <body>, and <script>.
<head>
This section should contain any necessary <meta> tags. As detailed in the "API Reference" section, these tags can create user input fields (like hue sliders, number pickers, etc.) or access the SignalRGB API to pull visual input from your primary application. Additionally, a <title> tag in this section will assign a label to your effect within the Signal app.
Let’s revisit the previous example for a clearer understanding:
<head> <title>Hue Cycle</title> <meta description="Stock hue cycle."/> <meta publisher="WhirlwindFX" /> <meta property="speed" label="Cycle Speed" type="number" min="1" max="10" default="2"></head>This header includes four tags: a <title> tag, and three <meta> tags, which cover the description, publisher, and a basic number slider. While static effect headers are usually small, effects that respond to actions on the screen may involve dozens of meters, each with multiple resolution settings. It’s important to stay organized and follow good naming conventions.
<head>
<body>
The body contains just one element - the <canvas> tag. The essential attributes for this tag are id, used for fetching the canvas in the script, and width and height. The standard dimensions for SignalRGB are 320px for width and 200px for height.
<body style="margin: 0; padding: 0;"> <canvas id="exCanvas" width="320" height="200"></canvas></body><body>
<script>
This tag is where the magic happens. There are three basic sections in this script, along with two functions that should be considered STANDARD for Lightscript developers: update and window.requestAnimationFrame.
Variable Declarations
All script-scoped variables should be declared together to simplify your development process. In the future, this will also include meter declarations, but for now, we have a simple selection.
- var c: This is used to fetch the canvas tag from earlier.
- var ctx: The 2D context of the canvas element, which is the editable area for your effect.
- height, width and hue: These are declared here to simplify the process.
Initial Update Call
At the bottom of the code block, I reference window.requestAnimationFrame(update). "Update" is the name of the function that handles the animation specifics. The updated state in each frame creates the illusion of motion for the viewers.
The method used here is crucial: Since each operation in your update function takes a small amount of time to execute, calling update() directly can cause a delay in the animations. For example, the first callback might think 100ms have passed, the next one 110ms, and so on.
By using window.requestAnimationFrame, the current timestamp is passed to the callback function and its nested callbacks, preserving the animation's state despite small execution gaps.
In short, use the window.requestAnimationFrame(callback) method to update your animation!
The Update Function
This function is central to a working Lightscript and needs to be as simple and streamlined as possible since it runs every frame. After the initial script load and function call, update will keep running through its internal window.requestAnimationFrame call.
In this example, each frame performs four main operations:
- Set the canvas fill style with ctx.fillStyle. This can be a color, pattern, or gradient, and will persist until it is overwritten by the next ctx.fillStyle call.
- Create a rectangle (with the previously set fill style) with ctx.fillRect(x, y, width, height). In this case the rectangle represents the whole canvas.
- Iterate the hue by speed, the user input variable located in the header.
- Bind hue to the 0-360 range in order to fit within HSL (hue, saturation, lightness) standard.
<script> // Variable Declarations ------------------------- // Get the canvas element from the DOM var c = document.getElementById("exCanvas"); var ctx = c.getContext("2d"); var width = 320; var height = 200; var hue = 0; // Update function -------------------------------- function update() { // 1 ctx.fillStyle = 'hsl('+ hue + ', 100%, 50%)'; // 2 ctx.fillRect(0, 0, width , height); // 3 hue+=(speed / 4); // 4 if (hue > 360) { hue = hue % 360; } // Re-call the function window.requestAnimationFrame(update); } // Initial update call ---------------------------- window.requestAnimationFrame(update);</script>This general pattern (set fill, draw shape, edit variables) is the standard for canvas animations.
- If the color is wrong, you missed a style fill.
- If the shape is wrong, you missed a shape fill.
- If nothing changes over time, you didn't edit your variables.
For more details and troubleshooting advice, check out our next page on HTML5 + JS.
<script>