Page Command

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).

LightwingPowerPointDiagram5Time 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.

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

<   Object Command                                             Introduction                                            Portrait Command   >