Effects Are Webpages
Effects in SignalRGB are called Lightscripts. A Lightscript is basically just a webpage with access to the SignalRGB API, and must follow a few simple rules to work as it should. Every Lightscript requires three HTML tags - <head>, <body>, and <script>.
<head>
Place any necessary <meta> tags in this section - covered in detail under "API Reference", these tags can create user input fields (hue sliders, number picker, etc.) or access the SignalRGB API for visual input from your primary application. Additionally, a <title> tag included in this section will label your effect in the Signal app.
Let's take a second look at the example from earlier -
<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>, and three <meta> tags that cover the description, publisher, and a basic number slider, respectively. Static effect headers tend to be small, but effects that respond to action on the screen could involve dozens of meters with several different resolution settings each. Stay organized and remember to use good naming conventions!
<head>
<body>
The body contains one thing only - the <canvas> tag. The required options for this tag are id for fetching the canvas in the script, and a width and height. SignalRGB's standard is 320 width, 200 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 to this script, and 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 nice simple selection. Var c is used to fetch the canvas tag from earlier - getting c's 2D context results in our editable canvas element var ctx. Height, width, and hue are declared here to simplify the process.
Initial Update Call
Here I am referencing the window.requestAnimationFrame(update) at the bottom of the code block. "Update" is the name of the function that contains the specifics of the animation, and its updated state in each frame is the process that creates the illusion of motion for your viewers. The method we use to call it here is very important - since each operation in your update function will take a small amount of time to run, only calling update() creates a situation in which one nested callback function thinks it is +100 milliseconds since start, the next thinks it is +110 milliseconds, then +120 milliseconds, and so on. The method window.requestAnimationFrame passes the current timestamp to its callback function and any nested callbacks, preserving the current state for any animations regardless of the small gap in execution. In short, use the "window.requestAnimationFrame(callback)" method to update your animation!
The Update Function
Central to a working Lightscript, this function needs to be as simple and streamlined as possible because it will run every frame. After the initial script load and function call, update will run and keep running through it's internal window.requestAnimationFrame call. In this example, each frame accomplishes four 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 canvas animation standard. 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 detail and troubleshooting advice, check out our next page HTML5 + JS.
<script>