All Lightwing content is organized into pages within script files, each of which typically has lines of additional commands to define objects, images, video and text for the page. Lightwing executes scripts one page at a time starting at the top of the file and proceeding downward. As each page is executed, it owns the whole display for a specific length of time. Then, when its time expires, everything on that page ends and control is passed to the next page in the script. The exception to this is the Global page, which has the special ability to display items continuously and across page time boundaries. Also, branch commands in the script can disrupt the normal downward execution flow to form loops and subroutines.
Every page must have a unique name which is defined by the first parameter to the page command. It can be any mix of alpha and numeric characters and some symbols including underscores and hyphens. Page names are used for branching during the execution of the script and for reporting execution status. The following example shows a typical page with a background image with a fade transition. This page also has some text and an animated object defined with additional commands.
Example of a Page with a Background Image, Text and an Object
page: Name time: 1.0, 5.0 transition: Fade image: PlanetEarthBackground.pvr
text: OpenSansRegular_50 type: "Hello World!"
object: Card
The following diagram illustrates the relationship between the time option parameters for the page command and the time option parameters for box, text, object and ticker commands on the page. Pages begin when the transition from the previous page ends and the durations of objects on the page begin after an optional start delay. Fade-in animations are measured from the end of the start delay and fade-out animations are measured from the end of the object duration (in the reverse direction), which may be shorter than the duration of the page. Note that boxes, text and objects have similar timing characteristics, but tickers do not have animation timing (other than their built-in scrolling).
Time Option
Defines the transition and duration times for the page in seconds. The first value is the amount of time for the animated transition from the previous page to the new page, or it can be zero to skip this animation completely. The second value defines the duration time of the page. The timings of all text, objects and animated background effects on the page are based on this duration time. When it expires, everything on the page expires with it and script execution continues with the transition to the next page. A duration time of zero is a special case which means the page never expires. This is unusual and should only be used to wait for a touch screen event, which requires a branch option to be defined for the page. Animated background effects will not function on pages with zero duration. These times can be specified as either floating-point values in seconds or integer (sexagesimal) clock time durations.
The time option can also be omitted completely, which is another special case that means the page has no duration time. This is useful for pages which contain only a branch command to construct a loop or subroutine.
Example Time Specifications
Time Duration Float Clock One Half Second 0.5 n/a One Second 1.0 1 One Minute 60 1:00 One and One Half Minutes 90 1:30 One Hour 3600 1:00:00 One and One Half Hours 5400 1:30:00 One Day 86400 24:00:00
Color Option
Defines a solid color for the page background. The background color is black by default and is only visible if the page has no image or video to display. Colors can be specified in one of three different formats, float values with a range of 0.0 to 1.0, integer values with a range of 0 to 255 or as a six digit hexadecimal value preceded with a hash symbol (HTML style). For all of these formats, the ordering of the values is red, green and blue. Alpha values can not be specified for page backgrounds as they must be opaque.
Example Colors Specified in Three Different Ways
Color Float Integer Hexadecimal Red 1.0, 0.0, 0.0 255, 0, 0 #ff0000 Green 0.0, 1.0, 0.0 0, 255, 0 #00ff00 Blue 0.0, 0.0, 1.0 0, 0, 255 #0000ff Yellow 1.0, 1.0, 0.0 255, 255, 0 #ffff00 White 1.0, 1.0, 1.0 255, 255, 255 #ffffff Black 0.0, 0.0, 0.0 0, 0, 0 #000000
Image Option
Defines one or more image names that will be displayed for the page background. Up to 8 names may be specified, optionally separated with commas. Each name may have a file name extension which defines the file type of the image. The supported types are BMP, PNG, JPG and PVR. The default type is PVR because this format loads more quickly than the others. If a BMP, PNG, or JPG image file can not be found, Lightwing will attempt to substitute it with another file of the same name but with the PVR extension.
If more than one image name is specified, they are drawn in the order they are given, so only the first image should be completely opaque. Subsequent images are optional, but can be used to construct multi-layered backgrounds with PNG images that contain transparent areas. Note that only PNG files support transparency, so any subsequent images should be PNG. Layering large images can significantly reduce the performance of Lightwing, so the number of layers should be kept as low as possible.
Also note that only some page transitions support layered backgrounds. The others will only display the first image (or video) layer during the transition time. Refer to the Animated Page Transitions chart below for details.
Example of a Page Background with 3 Image Layers page: FirstPage time: 1, 10 image: FirstImage.pvr, SecondImage.png, ThirdImage.png
Background images are scaled automatically to cover the entire page and should have approximately the same aspect ratio as the display. If an image is larger than the display, it is scaled down to fit. If an image is smaller than the display, it is scaled up to fit the display. Excessive scaling can adversely affect image quality, so background images should have approximately the same aspect ratio as the display to prevent the image from being noticeably stretched in one direction or the other. If the aspect ratio difference is excessive, use an image editing tool to crop it or consider using a Box or Object command to display the image at a different size. Those commands are much more versatile for displaying images.
By default, background images are rotated 90 degrees, automatically, if the orientation of the image does not match the orientation of the display. For example, if a landscape image is placed on a portrait display, or vice versa. This feature eliminates the need to have rotated copies of background images for different display orientations, while avoiding extreme distortion of the images. This feature works on single and multi-panel displays, provided that one or both dimensions of the display are one. Automatic rotation is not available on larger multi-panel displays. Automatic rotation can be disabled using the auto option.
Some image names are reserved and have special uses. These are always available without actual image files because they are built into Lightwing. Therefore, these names must not be used for any new images added into the images folder.
Reserved Image Names
Names Functions White Solid white color. Gray Solid gray color. Black Solid black color. Random Random static pattern. RSS Thumbnail image of current RSS item. Video Video substitute image. Previous Final frame of previous page. Background Solid background color of current page.
The Random image is a static pattern used by some effects. It has a smaller format (16 bits per pixel) than regular images, so it can only be used with effects that are designed for this format.
The Previous image is the final frame of the previous page. Whenever a page expires, the last frame is captured to use for the animated transition to the next page. This Previous image can be used as the first image layer for a multi-layered background on the next page with the image option. The Previous image may contain any combination of text, tickers, objects and/or background images from the previous page. However, it is always just a single image and never receives content from global page commands. Refer to the Playhouse Theater demonstration sign in the Lightwing SDK for an example of its use.
Tile Option
Defines horizontal and vertical image repeat counts for tiling the background image of the page. One or two float values can be specified in the range of 1.0 to 1000.0. The first value defines the count for tiling in the horizontal direction and the optional second value defines the count for tiling in the vertical direction. The background image is automatically scaled down as needed to meet the specified tile counts. Tiling is disabled by default. Tiling is only supported for background images, not video, and all image layers are always tiled the same.
Video Option
Defines the name of a video that will be displayed as the first layer of the page background. This requires a corresponding video command for the same name on the same page or on the global page preceding the page. A file name extension is not needed here because it is defined by the associated video command.
If the image option is also used, those images will be drawn over the video, so they must contain transparent areas for the video to be visible and only PNG files support transparency. Note that only some page transitions support layered backgrounds. The others will only display the first image (or video) layer during the transition time. Refer to the Animated Page Transitions chart below for details.
Background video is always scaled to cover the entire display. Since scaling can adversely affect image quality, it is best to use background video which is close to the same pixel resolution of the display, if practical. Background video should at least have approximately the same aspect ratio as the display to prevent the video from being noticeably stretched in one direction or the other. If the aspect ratio differs too much, background effects can be used to crop video or consider using an object command to display the video instead of using it as a page background. Displaying video with an object command is more versatile since the object can be scaled to match the aspect ratio of the video.
Example of a Page with a Video Background
page: FirstPage time: 1, 10 video: DiskCirclesBlueLoop
video: DiskCirclesBlueLoop.lv2
Auto Option
Allows the automatic rotation of background images and/or video to be enabled or disabled. This parameter can be specified as on or off. It is on by default.
Background images and/or video are automatically rotated 90 degrees if the orientation of the first image layer or video does not match the orientation of the display. For example, if a landscape image is placed on a portrait display, or vice versa. This feature eliminates the need to have rotated copies of background images for different display orientations, while avoiding distortion of the images. Only the first image layer is tested to decide if rotation is required. If the page has a background video, the dimensions of the video are tested instead of the image. If rotation is required, the same rotation is applied to all of the image layers and/or video for the page.
This feature works on single and multi-panel displays, provided that one or both dimensions of the display are one. Automatic rotation is not supported on larger multi-panel displays.
Transition Option
Defines the style of animation that is used to transition from the previous page to the new page. Lightwing features over 40 different transition styles from simple fades to geometric louvers and most can be fined-tuned with the optional direction option. The default transition is Fade.
Some transitions support using multiple image layers for page backgrounds, as indicated in the chart below. The other transitions will only display the first image (or video) layer during transitions. Also, some transitions support using arbitrary image effects for the page backgrounds as well. Otherwise, transitions will use their own default effects. Finally, some transitions support effects only partially, which means some directions of the transitions support effects and while other directions do not.
The circular transitions (Radar, Burst, Disk, Rings and Fresnel) have the special feature of acknowledging touch positions when used with a touch screen panel. This provides positive feedback to the user of where touch events are detected. Otherwise, these transitions, are drawn from the center of the display.
The rate of the animations is defined by the first time option on the page command. Longer time durations will cause transitions to animate more slowly. A transition time of zero will cause the transition to be skipped entirely. The best way to preview and select transitions is to run the TestTransitions.lws script provided in the Lightwing SDK.
Animated Page Transitions
Name Layers Effects Touch Directions
Fade Yes Yes No None
FadeBlack Yes No No None
FadeGray Yes No No None
FadeWhite Yes No No None
ZoomIn Yes Yes No None
ZoomOut Yes Yes No None
SpinIn Yes Yes No None
SpinOut Yes Yes No None
Implode Yes Yes No None
Explode Yes Yes No None
WavesSmall Yes Yes No None
WavesMedium Yes Yes No None
WavesLarge Yes Yes No None
Flip Yes Yes No Top, Bottom, Left, Right, None
Slide Yes Yes No Top, Bottom, Left, Right
SlideBounce Yes Yes No Top, Bottom, Left, Right
Door Yes Yes No Top, Bottom, Left, Right
DoorCenter Yes Yes No Top, Bottom, Left, Right
Tumble Yes Yes No TopLeft, TopRight, BottomLeft, BottomRight
Twist No Yes No Left, Right
Carousel Yes No No Left, Right
Cube Yes No No Left, Right
Curl No Yes No TopLeft, TopRight, BottomLeft, BottomRight
Wipe Yes Yes No Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, BottomRight
LouverSmall No Yes No Top, Bottom, Left, Right
LouverMedium No Yes No Top, Bottom, Left, Right
LouverLarge No Yes No Top, Bottom, Left, Right
LouverDelaySmall No Partial No Top, Bottom, Left, Right
LouverDelayMedium No Partial No Top, Bottom, Left, Right
LouverDelayLarge No Partial No Top, Bottom, Left, Right
LouverBlankSmall No Partial No Top, Bottom, Left, Right
LouverBlankMedium No Partial No Top, Bottom, Left, Right
LouverBlankLarge No Partial No Top, Bottom, Left, Right
LouverBlankDelaySmall No Partial No Top, Bottom, Left, Right
LouverBlankDelayMedium No Partial No Top, Bottom, Left, Right
LouverBlankDelayLarge No Partial No Top, Bottom, Left, Right
Radar No Partial Yes Left, Right
Burst No Partial Yes Left, Right
Disk No Partial Yes Left, Right
RingsSmall No Partial Yes Left, Right
RingsMedium No Partial Yes Left, Right
RingsLarge No Partial Yes Left, Right
FresnelSmall No Partial Yes Left, Right
FresnelMedium No Partial Yes Left, Right
FresnelLarge No Partial Yes Left, Right
Direction Option
This option provides direction control for most animated page transitions. The chart above defines which directions can be used with each transition.
The direction variable touch is defined as the direction that was detected from the last directional touch (swipe) event from the previous page. It can only have one of four values, Left, Right, Top or Bottom. Therefore, touch should only be used with transitions that support at least some of those directions. To use this variable, the previous page must have a touch: dir option to set this variable.
Page Transition Directions
Name Short
None n
Top t
Bottom b
Left l
Right r
TopLeft tl
TopRight tr
BottomLeft bl
BottomRight br
Touch
Light Option
Defines the direction of light for all boxes on the page. This is specified as three floating-point values for the X, Y and Z directions. The default light direction is 1.0, 1.0, -1.0. This option only applies to boxes which are drawn with a lighting effect, such as SolidColorLight. Since boxes are always flat and colored solid, lighting effects can only be visible as color gradients when positioned at appropriate angles with respect to the light direction. The light directions for objects is defined in Blender when they are created and lighting is not supported for backgrounds, text or tickers.
Single Option
Forces the entire page to always be drawn regardless of whether the player is configured as part of a single or multi-panel display. This parameter can be specified as on or off. The default is off. When this option is enabled, multi-panel rendering is disabled for all the content on this page.
Speed Option
Defines a speed multiplier for all of the animations on the page, including all objects, text and tickers. This is a convenient way to adjust the speed of an entire page without much editing. This is a floating-point value which must be between 0.01 and 100.0. Values below 1.0 decrease the speed and values above 1.0 will increase the speed.
Touch Option
Defines the polarity for which touch screen events will be recognized for the page background. Touch events for the current page background always supersede any touch event defined for the global page background. However, all background touch events are superseded by touch events defined for boxes, text, tickers or objects on the current or global page, if they exist. Background touch events can be used to catch touches that miss other objects on the page. To ignore misses, simply do not define a touch event for the background.
This parameter can be specified as on, off, both or dir. The default is on. A touch on event means a finger has made contact with the touch screen. A touch off event means a finger has broken contact with the touch screen. Touch both means that both on and off touch events are recognized. This option requires that a jump, call or return option must also be specified for the page command to define the branch page that will be executed when the touch event is detected.
The dir touch option allows one of several branch pages to be selected based on swipe direction. A touch swipe event is when a finger is dragged on the display at least 10% of the width or height of the display and released. The dominate direction of movement at the point of release selects the branch page. One of four swipe directions can be detected, left, right, top and bottom. This requires that either two or four branch pages be defined for the touch branch option for the page. The best practice is to define all four page names, even if only two are actually needed. The dir option can not be used with the return option.
Touch events are not recognized during page transitions.
Jump Option
Defines a branch page to execute when a touch event occurs on the page background with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Jump command, except that no branch condition options can be used here.
Call Option
Defines a branch page to execute when a touch event occurs on the page background with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Call command, except that no branch condition options can be used here.
Return Option
Defines that a branch page from the call stack will be executed when a touch event occurs on the page background with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Return command, except that no branch condition options can be used here.
Effect Option
Defines an effect to be used to draw all of the layers of the page background instead of the default background effect (background.pfx). A single parameter defines the name of the effect to use. A PFX extension is appended to the end of this name to construct the file name of the effect. Effects must be located in the effects folder regardless of whether they are applied to objects, fonts or backgrounds. Most of the image effects supplied with the Lightwing SDK can also be used for page backgrounds. A specific image or video name may be specified in the effect file, but most of the supplied effects specify “Default”, which means to use the image or video name specified by the image or video options to the Page command, respectively.
Arg0 and Arg1 Options
Defines effect-specific parameters for a selected background effect. Up to four floating-point values are passed to the effect for arg0 and, optionally, another four floating-point values for arg1, to draw the background. The meaning of these values depends on the selected effect. These parameters are required by some effects, but ignored by the default background effect. To determine the appropriate values for particular effects, refer to the comments in the effect files themselves.
Example of a Page with a Background Effect and Arguments page: PageName time: 1, 10 image: PlanetEarthBackground.pvr effect: ImageZoom arg0: 0.1, 0.1, 3.0, 3.0