The most important part of any Lightwing project is creating a script file. Lightwing scripting is easy, yet powerful. This scripting guide is the best place to start. The Lightwing SDK provides many examples of scripts that can be copied into a new project to use as a starting point or copy and paste individual pages from existing scripts that already have the desired features. The scripts provided in the Lightwing SDK include Tests, Demos and Tutorials. Start your project by editing the tutorial scripts.
Example Scripts in Lightwing SDK
Type File Names Locations Tutorials Tutorial_<Number>_<Topic>.lws Lightwing\scripts Demos Default.lws Lightwing\demos\<DemoName>\scripts Tests Test<Category>.lws Lightwing\scripts
The Coordinate System
The Lightwing coordinate system makes it easy to position objects and text on the 2 dimensional space of the display and in 3 dimensions when depth is actually needed for 3D object animation. The range of coordinate values is 0 to 100 and is the same in the horizontal, vertical and depth directions (x, y and z respectively) with floating-point precision. So, the top of every page is coordinate 0 and the bottom is coordinate 100, regardless of the actual pixel dimensions of the display. Likewise, the left edge of every page is coordinate 0 and the right edge is coordinate 100, regardless of the display.
Every page is logically the same size as the display even though their physical resolutions are usually different. This makes it easy to port Lightwing content to other displays with different dimensions. Even porting content between displays with differing aspect ratios, such as landscape and portrait displays, is simplified because Lightwing coordinates are consistent in both directions.
Text is drawn at the front of the coordinate space (z = 0) by default and background images and video for pages are always drawn at the extreme back of the coordinate space (z = 99 to 100). Text and backgrounds are drawn with orthogonal projections by default so that their sizes are not affected by their depth positions.
Objects are drawn at the front of the coordinate space (z = 0) by default, unless other z coordinates are specified. Objects are usually drawn with perspective projections, so their apparent size depends on their depth. This allows depth coordinates to be unspecified, unless they are actually needed to position objects at specific depths to avoid collision. So, new developers can use Lightwing like a familiar 2D system and ignore depth concerns, but know that 3D is available when needed for more advanced animations.
This diagram illustrates the Lightwing coordinate space. Conceptually, it is a 3 dimensional cube where the front face of this cube is the plane of the display and the origin point (0.0, 0.0, 0.0) is at the top left corner of that face. Note that the center of the display is always at coordinate (50.0, 50.0). Most objects are drawn centered at (50.0, 50.0, 0.0) by default, but can be repositioned anywhere, including outside of the visible coordinate space.
General Script Syntax
Lightwing script files consist of lines of commands with command options and parameters. Commands are grouped into pages which control their execution order and timing. All commands require at least one mandatory parameter, which must appear first, before optional parameters. Any number of additional required and optional parameters may follow on the same line, in any order. Commands options define and enhance the function of commands and they all have default values that are used if omitted. Most command options can be combined, except where specifically noted. White space delimits commands and parameters. A good practice is to be consistent in ordering command options and use tabulation to make scripts easy to read. Comma symbols can also be used to delimit parameter lists, but this is optional. Indentation, extra white space and blank lines are ignored, but encouraged to group commands into pages.
Command and command option keywords should be lower case and must always end with a colon symbol. Parameters to commands should use capitalization and must not contain colon symbols. All of the images, videos, fonts, effects and objects provided in the Lightwing SDK are consistently named this way. Most command and command option keyword names can be abbreviated to their first 3 characters.
Lightwing actually ignores case for commands, command options and page names. However, file names are case sensitive on Linux, although not on Windows. Therefore, in order for scripts to run the same on Linux and Windows it is essential to consider all file names as being case sensitive. Windows allows some symbols in file names, such as spaces and commas, that are illegal on Linux and will cause script parsing problems. So, these symbols must not be used in the file names of any content files. The best practice is to rename all content file names to remove spaces and commas and respect case. Otherwise, content developed on Windows may not play when it is copied to the Linux player. Renaming image and video files is usually needed anyway since digital cameras tend to generate cryptic names. Renaming those files early in a project makes things easier. Underscore and hyphen symbols are permitted in file names and can be used to replace spaces and commas.
Since many command options are often combined, this can lead to long line lengths in script files. Backslash symbols (\) can be used to break long lines into shorter lines by placing a backslash at the end of lines that are continued on the next line. However, lines must be broken between complete command options and not within parameter lists. Do not separate parameters from their preceding option keywords.
Example of using a backslash symbol to break a long command line
text: GalatiaRegular_90 time: 0, 10 fade: 0.5, 0.5 zoom: 1, 0, 1, 0 \
position: 5, 5 bounce: 1, 0, 0 slide: 1, 1 align: TopLeft type: "Hello World!"
Comments
Comments are good to document what pages do or how script code works. This can be any information important to the author and should make it easier for others to understand how to maintain and modify your script. Lightwing recognizes the same comment symbols familiar to C/C++ and Java developers, except that comment symbols can not be embedded in the middle of script lines. Any line which begins with double forward slashes (//) is considered a single line comment and the entire line is ignored. Any group of lines which begins with a forward slash and asterisk combination (/*) is considered a comment block and all the lines in the block are ignored until the end of the block, which is indicated with a reverse asterisk and forward slash combination (*/).
Examples of Using Comments
// This is a single line comment about the first page.
page: FirstPage time: 1, 10
/* This is a comment that disables a page with multiple lines.
page: SecondPage time: 1, 10
text: GalatiaRegular_10 type: "Hello World!"
*/
These comment symbols are also quite useful for debugging problems with Lightwing scripts, by temporarily disabling pages or lines from the script without actually deleting them.
The following pages detail every Lightwing command with an individual page for each organized alphabetically. Each page details all of the available options for each command and gives syntax examples of their use in Lightwing scripting. Also refer to the tutorial scripts provided in the Lightwing SDK for more examples of use.
Summary of Lightwing Commands
Commands Functions
Audio Define a wave audio file to be played.
Box Draw a rectangular box with colors, an image or video.
Call Call a subroutine in the same script.
Camera Define if a camera is required.
Chain Chain to a page in another script.
Data Define a dynamic data channel read from a local CSV file.
Global Define content to update the global page.
Input Define the default input device for user input.
Jump Jump to another page in the same script.
Link Link to a subroutine in another script.
Object Draw an animated 3D object with images or video.
Page Define a page for content.
Portrait Define required orientation of the display.
Return Return from a script subroutine.
RSS Define an RSS channel feed from the web.
Shadow Define drop-shadow parameters for a font.
System Call a Linux system shell command.
Text Draw constant or dynamic text with a font.
Ticker Draw animated ticker with constant or dynamic text with a font.
Toggle Define a touch region for a toggle control.
Touch Define if touch capabilities are required.
Track Define a touch region for a tracking control.
Version Define required version of Lightwing.
Video Define a video to use on a box, object or page background.
Write Write data channel arrays back to the file system.
Text and Tickers
There are several ways to create text with Lightwing, use the Text or Ticker commands, embed text into image or video files or embed text into object files. The Text and Ticker commands are similar except that Text has more options to control built-in animations. The Ticker command always animates text continuously in a left to right horizontal scroll.
The Text and Ticker commands provide powerful capabilities that are easy to use with minimal experience. This is one of the great features of Lightwing. Lightwing will render professional, presentation quality text directly from scripts, RSS channels or a CSV file, in any available font, size, color, with or without animations, font effects and/or drop-shadows with no additional software required. This makes changing text as simple as editing the script or CSV file and copying the updated file to the player. The Text and Ticker commands are limited to rendering 2D text (although fonts may have a 3D look), but that is what most projects need.
Sometimes, it may be preferable to embed text into image or video files, instead of using the Text or Ticker commands. This makes it more difficult to edit the text, but more elaborate animations are possible – created with other tools. Or, if you already have images or video created with other tools, this approach makes sense.
The third option is to embed text into objects using Blender. This provides ultimate flexibility because text is rendered with true 3D models, but some knowledge of Blender is required. The best approach is often a combination of these methods. Use the Text and Ticker commands for text that is likely to change frequently, and embedded text where it will not change.
Ways to Create Text
Approach Advantages Disadvantages Tools Required Text and Ticker Commands Easy, built-in fonts, animations, drop-shadows 2D only Text editor Embed in Images or Video Portable from other tools Difficult to edit Image or video editor Object Text Advanced animations. Allows full 3D Difficult to edit Blender
These approaches to text creation can also be mixed as appropriate for your project. If you are new to Lightwing, simply cut and paste sample Text or Ticker commands from the TestText.lws test script to get started.
Script Branching
Lightwing executes pages from the top of scripts downward until the bottom of the file is reached, at which point Lightwing will exit. However, Lightwing features five branching commands which can be used to construct loops, subroutines and modular scripts. These commands are Jump, Call, Chain, Link and Return. These commands execute only when the current page expires, regardless of their order on the page. Some commands feature branch options by the same names (Jump, Call and Return) which execute immediately when a touch event occurs. In other words, they abort the current page.
The Jump and Call commands are used to branch to other pages within the same script. These commands feature mostly the same condition options and only require the name of a page to branch to within the current script when the current page expires.
The Chain and Link commands are used to branch to other scripts. These commands feature the same condition options and only require the name and/or path of a script to branch to when the current page expires. An optional second parameter may also be specified which names a page in the target script. If omitted, the target script will begin execution at the first page in the file.
Lightwing features two internal LIFO stacks named the page and script call stacks, which store return page and script names for the Return command, respectively. The Call command stores return page names on the page stack and the Link command stores return script names on the script stack. Both stacks are 64 levels deep, so this is the maximum number of Call or Link commands that can be nested. If either stack overflows, Lightwing will report the error and exit.
The Return command is used to branch back to the page or script that executed the previous Call or Link command, respectively. The Return command always attempts to return from the previous Call command first, within the same script. But, if the page call stack is empty, Lightwing then attempts to return to the previous script that executed the last Link command, instead. If the script link stack is also empty, Lightwing will report a warning message and continue execution in the current script. The Return command has no parameters since the internal stacks supply the required page and script names.
The Link and Chain commands make it possible to create very large Lightwing projects which are not limited by the amount of memory available. Since there is no limit to the number of scripts that can be linked or chained, the ultimate size of any project is only limited by the amount of space available to the file system.
Touch Events and Controls
Lightwing provides tightly integrated support for touch-screen displays in two ways, touch event branching and touch controls. Touch events can be detected within the boundaries of pages, boxes, text, tickers and objects and they typically alter the order of script execution by branching to another page. Touch event detection is enabled by simply adding a jump, call or return option to box, text, ticker, object, page or global commands. These options define the pages that Lightwing will branch to when touch events occur. These branches are only conditioned on the occurrence of the touch events, so other branch condition options can not be combined here. However, the touch option can be combined to provide more control over the polarity of touch detection, but this is usually unnecessary.
Touch event regions may overlap the regions of other touch events on the same page. When this is done, it is important to consider the priorities of touch events of different types of objects. For example, objects with touch events will have priority over touch events for page backgrounds that fall within the area where they overlap. If multiple objects of the same type have overlapping touch regions, then their order in the script determines their relative priorities. The relative priority increases as commands descend down the page script.
When objects with touch events are placed on the global page, they take priority over any overlapped touch regions on the current page. However, there is one exception to this – even though the global page does not have a background image or color, it does support a background touch event that always has the lowest priority of all, even lower than events on the current page.
The following chart details the relative priorities of touch events for different types of objects when their regions overlap.
Touch Event Priorities
Touch Event Type Priorities Toggle Controls 1 (Highest) Track Controls 2 Tickers 3 Texts 4 Boxes 5 Objects 6 Page Background 7 Global Page Background 8 (Lowest)
Another way Lightwing supports touch-screen displays is with the touch control commands Toggle and Track. These commands provide state and numerical value variables that are controlled by users touch input. These variables can then be used to control input parameters to other Lightwing commands. These commands make it easy to construct interactive buttons and tracking controls with virtually any appearance for interactive digital sign or touch-kiosk applications. Use a data channel to initialize touch controls with values read from a CSV file or to export touch control values to a CSV file.
Note that the Windows version of Lightwing uses mouse clicks to emulate touch events so that touch-enabled content can be developed on Windows using just a mouse. Examples shown here require a touch capable display to function on a Linux player. Such content should have the touch: on command before the first page, as shown in the TestTouch and Tutorial scripts for touch controls in the Lightwing SDK. This causes Lightwing to abort and report an error message if a touch capable display is not detected when scripts are parsed, but only on Linux.
Data Channels
Lightwing reads and writes information to/from the local file system using two-dimensional arrays called data channels. Any number of required data channels can be open and read at the start of a script. Data channels are global to the entire script, so array contents can be used by any pages in the script to display dynamic information or to initialize the starting values for touch controls. Touch controls can be used to modify the values of items in data channel arrays, which can then be written back to the file system using the write command. This is typically done before a script ends so that touch control settings are preserved and can be retrieved when the script is run again.
Custom Effects
When Lightwing draws boxes, text, tickers, images, objects and video, it uses effects which are defined by OpenGL ES shader programs. This is how Lightwing offloads most of the graphics processing to the GPU and achieves such impressive performance. Lightwing has a set of default effects that are used to keep scripting simple, but these defaults can also be overridden, when necessary, to accomplish custom and extraordinary effects. The Box, Page, Object, Shadow, Text and Ticker commands all feature options to define effects to override the default effects.
Effect files are written in GLSL (OpenGL ES Shading Language) and new effects can be created by adding them to the effects folder. No special development tools are required since Lightwing compiles effects automatically, as needed. Some understanding of effects is useful, but GLSL programming is an advanced topic and creating new effects is beyond the scope of this guide. The Lightwing SDK provides many effects that are ready to be used simply by copying their names into your scripts.
Effect files have section labels in square brackets. The section labelled [TEXTURES] defines the names of all the images required by an effect. Textures and images are roughly synonymous but are stored in different formats. Whenever Lightwing loads an effect, it must find images with matching names for all of the textures listed in this section or an error will be reported. However, there are some reserved image names which Lightwing handles differently, including Default. Many effects specify Default for textures which has a special meaning. It causes Lightwing to get the image name from the object that referenced the effect. This allows objects to define specific images, but still be overridden by an effect when desired, without the need to modify the object. Finally, those image names can also be overridden by images specified with the image or effect options to the Object command.