Object Command

Lightwing features powerful 3D animation capabilities which are accessed primarily through the Object command. This command loads object files with their associated effects and images and plays the object’s animation. Object files contain geometric models of 3D shapes as a minimum, but usually have animations and texture coordinates for mapping images or video to the models as well. Objects may also have solid colors or lamps for directional lighting effects.

Most objects are designed to be reusable so that their images or video can be changed easily with options to the Object command. The options that control this are summarized below:

Object Command Options for Mapping Images and Video

        Names                Purpose
    
        image:                    Defines substitute images for an object. 
        video:                     Defines substitute video for an object. 
        effect:                     Defines substitute effects for an object. 
        arg0: and arg1:     Defines parameters for effects.

Object files have a POD file name extension and are created using the Blender 3D authoring tool and exported with the PVRGeoPOD plugin. Blender is a powerful open-source tool that requires some time to learn and is beyond the scope of this guide, so it is recommended only for more experienced users. For your first sign project, utilize the prepared objects that are provided in the Lightwing SDK instead. These can simply be copied into a new project without using Blender. Refer to the section on Creating Objects for more information about creating new objects with Blender.

The colors and images displayed on objects are called Materials in Blender. When an object is loaded, all of its required materials must be found. Lightwing equates material names to effect file names and expects each material named in the object to have a corresponding effect file in the effects folder. Effect files list the default images (textures) that will be mapped to the object model. This allows objects to name specific images and effects when necessary, or the defaults can be overridden with the image, video and/or effect command options. The effect command option will substitute materials with alternate effects, the image command option will substitute images with alternate images and the video command option will substitute a default image name with a video. These options make it easy to reuse provided objects with new images or video. The best way to appreciate and select from the objects provided in the Lightwing SDK is to run the TestObjects.lws test script.

The Object command also allows special effects to be applied to any image or video with the effects option. Effects can enhance the appearance of images and make them visually more effective with various enhancements. Some effects are static while others are animated throughout the time duration of the object and can include pan, zoom, blur, blend, scatter, color, reflection and refraction effects, for example. The best way to appreciate and select effects is to run the TestEffectsImages.lws test script provided in the Lightwing SDK.

The Object command requires the name of an object. The POD extension is appended to the end of this name to construct the file name of the object file, which must be located in the objects folder. The PFX extension is appended to the end of effect names to construct the file name of effect files, which must be located in the effects folder.

    Example of a Page with Object Commands

    page: PageName    time: 1, 10
        object: DiskSpinYellow
        object: CardSpin    image: CaptainChristopherPike.pvr
        object: CardSpin    video: OvalCirclesWhiteLoop
        object: CardSpin    effect: Material, ImageBlendGradient, CaptainChristopherPike.pvr

When an object contains multiple mesh nodes, they are drawn in alphabetic order of the node names as defined in Blender. This is particularly important when object nodes are overlapped and the depth option is enabled.

Time Option

Defines the start and animation duration times for the object in seconds. If not specified, the default start and duration times will be the same as for the page that this object is on. These can be specified as either floating-point values in seconds or integer (sexagesimal) clock time durations. Refer to the Page command for examples. Start times can be prefixed with a plus symbol (+) which means the new start time is the sum of the specified time and the start time from the previous object command on the same page. This allows object commands to be duplicated in the script file without the need to manually add time values.

Fade Option

Defines the time in seconds for the object to fade-in and fade-out, when it appears and disappears, respectively. Sexagesimal format can not be used here because fading time should never be more than a few seconds at most. The fade-out normally occurs during the end of the object’s animation duration time so that it will become completely invisible at the same point in time its animation expires. Alternatively, the fade-out time can be specified as a negative value which means that the object will persist past its animation time and fade-out at the end of the page duration time. In this case, any animation for the object will stop, but its fade-out is delayed to the end of the page, rather than the end of the animation.

Position Option

Defines a position for the model in the object to be drawn on the display. Objects can contain models with multiple nodes and their default positions are set when the objects are created according to how the camera in the object is oriented. However, the models in most of the objects provided in the Lightwing SDK are centered at the origin point (0.0, 0.0, 0.0) by default. This means that most objects will be drawn centered around the top left corner of the display by default, because that is the location of the origin on the display. However, the position option will adjust where the object is drawn. For example, to center the object on the display and at the front, use coordinates 50.0, 50.0, 0.0. To center the object on the display, but be behind text or tickers, increase the depth coordinate, such as 50.0, 50.0, 10.0.

Any coordinate in a position can be prefixed with a plus symbol (+) which means the new position is the sum of the specified coordinate and the same position coordinate from the previous object command on the same page. This allows object commands to be duplicated in the script file without the need to manually add position values.

On multi-panel displays, Lightwing requires all objects with perspective projections to be positioned at a depth of zero (0.0) in the coordinate space.

Scale Option

Defines scaling factors for the model in the object. The models within objects have default sizes set when the objects were created. The scale option will stretch or reduce the default size of the object’s model in any direction. The default scaling factors for objects are 1.0, 1.0, 1.0, which disables scaling.

Rotate Option

Defines rotation angles for the model in the object in degrees. Up to three floating-point values can be specified, which correspond to rotations on the x, y and z axis, respectively. Positive degree values indicate clockwise rotation, whereas negative values indicate counter-clockwise rotation. The default rotations for objects are 0.0, 0.0, 0.0 degrees.

Rate Option

Defines an animation rate for an object that overrides the default animation rate of the object. This is specified as a positive floating-point value. The default animation rate for objects is defined by the time it takes to draw all of the frames of the object once. Therefore, it is affected by the number of frames in the object as well as the time duration of the object, which defaults to the duration time for the page, if not specified. This option allows the animation rate to be defined independent of the number of frames in the object and its time duration.

Frame Option

Defines a specific frame of the object to display. Objects may contain any number of animation frames which are usually played sequentially from the first frame (zero). This option effectively disables the animation from the object and instead displays the single frame that is indexed by this value. This frame index is clipped to the valid range of frames that are available from the object. A track control name can be used here to make the object’s animation controlled by a tracking touch control. This option overrides the Rate and Loop options.

Loop Option

Enables or disables repeating an object animation continuously. This parameter can be specified as off or on.  It is off by default.

Reverse Option

Enables or disables reversing the object animation direction. This parameter can be specified as off or on.  It is off by default.

Ortho Option

Defines if the object is drawn using an orthographic or perspective projection. This parameter can be specified as off or on and it’s on, by default. Orthographic projections cause the sizes of objects to appear the same regardless of their depth position. This is good for objects that do not have much depth. For objects that do have significant depth, use the perspective projection mode for a more realistic 3D appearance (ortho: off). In this case, the object’s apparent size will be proportionate to its depth, or distance from the camera.

Perspective projections are not yet fully supported on multi-panel displays, so the ortho option must be on for all objects in content for multi-panel displays.

Cull Option

Enables or disables back-face culling when drawing the object. This parameter can be specified as off or on.  It is on by default.

Depth Option

Enables or disables depth-testing for drawing the object. This parameter can be specified as off or on. Depth-testing is off by default, which means that drawn objects will be obscured by other objects when they are drawn afterwards, regardless of their depth positions (Z coordinates). Draw order is defined by the order the objects are listed on the page from top to bottom, rather than by their start times, which may be in a different order. When depth-testing is enabled, objects will be obscured by other objects which have lower depth positions (Z coordinates), regardless of the order in which they are drawn.

Video Option

Defines the name of a video that will be drawn on the object instead of the default image named in the object or the effects associated with the object. The video must have already been established with a video command either on the same page or on a preceding global page. This video can then be invoked with the reserved name Video to substitute for any image for the object.

Image Option

Defines one or more substitute images that will be drawn on the object instead of the default images named in the object or the effects associated with the object. If used without an effect option, images are substituted in alphabetic order as they are named in the object. If used with an effect option, images are substituted for the materials named by the effect option. This option is not as versatile when used without the effect option because the substitute effect will always be the default image effect named Image, but this option has the advantage that material names are not required. To override specific images by the material names that reference them, use the effect option also.

Each image 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. If a BMP, PNG, or JPG image can not be found, Lightwing will substitute it with another file of the same name but with the PVR extension.

There are some reserved image names which can be used with the image command option which 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                  Function
    
        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.
        Default                    Default image defined by the object.
        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. But, the Previous image can also be used by objects 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.

RSS Option

Defines the name of an RSS channel that will provide thumbnail images for the object. This RSS channel must have already been established with an RSS command at the top of the script file with a matching RSS channel name and it must enable thumbnail images with the thumbnail option. Not all RSS websites provide thumbnail images and even those that do typically do not provide thumbnail images for every item in the channel feed. Therefore, when no image is available for the current item, Lightwing attempts to display the channel image instead and when neither image is available, the object will not be drawn until the RSS channel steps to an item which does have a valid image.

This option can not be combined with the image or video options. Refer to the TestRSS.lws script in the Lightwing SDK for an example.

Speed Option

Defines a speed multiplier for the animations of the object. This is a convenient way to adjust the speed of an object’s animations without modifying the actual object. 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 object. Touch events for objects have precedence over events for backgrounds, boxes, text and tickers.

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

Toggle Option

Defines a toggle control which enables and disables the object and its touch events. If a toggle control name is specified with this option, the object will only be drawn when the toggle control is active, otherwise the object is invisible and its touch events are not processed either. This toggle control name must be defined either on the same page or the current global page. However, toggle controls can be defined before or after the Object command provided they are defined on the same page.

Effect Option

Defines substitute effects to be used to draw the images of the object instead of the default effects named by the object. The first parameter is the name of the effect to replace. This must match a material name in the object. The second parameter must name a substitute effect. The PFX extension is appended to the end of the effect name to construct the file name of the effect and effects must be located in the effects folder. Note that the terms effect and material are roughly synonymous in this context. Blender uses the term material, but Lightwing maps each material to an effect, so material names directly correspond to effect names.

Many objects reference a material named Material, which is a reserved name used as a place-holder and intended to be substituted with other effects without the need to modify the object or effect files. Therefore, the effect option is required to define the actual effect names when using an object with a material named Material.

The third parameter can name a substitute image to use instead of the first image named by the effect or in the object. This parameter is optional and serves the same purpose as the image option. If not specified, the image will default to the name specified in the effect.  If that name is Default, then the image name is taken from the object instead. Alternatively, if the image name is Video, then a video stream is used instead of an image. In this case, the object command must have a video option which defines the name of the video.

Arg0 and Arg1 Options

Defines effect-specific parameters for a selected image 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 image. The meaning of these values differs for each effect. These parameters are required by some effects, but ignored by the default image effect. To determine the appropriate values for particular effects, refer to the comments in the effect files themselves.

      Example of an Object Command with an Image Effect and Arguments

        object: CardTumbleLeft    image: CaptainChristopherPike.pvr    effect: Material, ImageFrame    arg0: 2.0, 2.0, 2.0, 1.0    arg1: 0.05, 0.05

 

 

<   Link Command                                             Introduction                                            Page Command   >