VMP Flash 9 Properties and Functions

1 General Information
2 Differences between 'SWFView' and 'SWFView9'
- 2.1 Unsupported in 'SWFView9'
- 2.2 Changed Behavior
3 Inherited MTSTimeElem properties
- 3.1 Controlling Flash's Playing State
- 3.2 Flash's Time access and control
4 Properties of SWFView9 animator
5 Functions of SWFView9 animator
6 Functions of Adobe Flash 9 native DLL exposed by SWFView9 animator
7 Scripting
8 Scaling
9 Flash 9 Full-screen support

General Information

The Flash 9 animator takes advantage of Flash 9's robust API and the latest Flash technologies including AS2/AS3 scripted animation and FLV videos with full screen support. Essentially, the Flash 9 animator serves the same purpose as the old Flash 5 component. The main difference is that the new system uses native Flash DLL for rendering and is therefore compatible with all Flash versions up to version 9. In some (simple) cases it is possible to replace 'SWFView' in the content with 'SWFView9' and it will work. However, just switching the animators is not guaranteed to work, and is not supported.

Differences between 'SWFView' and 'SWFView9'

Unsupported in 'SWFView9'

Many properties originating from the ZoomView animator that were used to precisely position Flash content are no longer supported. This will now have to be done inside the Flash movie. Here is the full list: PosU, PosV, Zoom, OveZ, TarU, TarV, TarZ, IncU, IncV, IncZ, TimT, DelU, DelV, DelZ, Del0, ScrX, ScrY, UMin, VMin, ZMin, ZMax, Zfit, Snap, zi_x, zi_y, iz_x, iz_y, Norm, Init, Irec
Other Unsupported Properties:

Property	Description
SVG	SVG rendering was implemented by `'SWFView'` animator because it was using same vector-rendering code as our implementation of Flash 5. It will not work in `'SWFView9'`.
LayerCache	Obsolete property used to control aspects of rendering Flash content by VMP rendering engine
UseDirtyRects	Obsolete property used to control aspects of rendering Flash content by VMP rendering engine
Font	Obsolete
opac	Used for specifying transparency for the whole movie. Unsupported.
rtim	Used for specifying if frames are skipped when playback can't keep up with frame rate. Unsupported.
Clip	Used to set an additional clipping rectangle. Unsupported.
Base	Used to specify base path. Determined automatically based on MTX or HTML path.
Quty	Used to specify quality. Unsupported.

Changed Behavior

<MTSBaseComponent ... PreserveCamera="x" /> - applies for x "1" or "2":
- Old behavior - Caused 2d content (Pre- and Post- animators) to be drawn at the same screen positions after switching to HyperView or SuperView(H/S View). Often H/S View content is larger than the plugin area. Therefore, when content launches into H/S View, Flash elements in Pre/Post animators stay in place, while some Flash content which is not visible (because it is beyond the plugin area - off-stage) will become visible. In other words, the plugin rectangle is always used to determine transform for all Flash content, while the H/S View rectangle is used to determine drawing boundaries.
- New behavior - When using native Flash DLL, we can only give it one rectangle. We decided to use the plugin rectangle. This means that Flash 9 content will not move after switching to H/S View. The difference is that Flash 9 will not draw off-stage content.

rst_ (Reset). Similar effect can be achieved by using new write-only property Reload.
- Old behavior - Caused the Flash 5 animator to effectively reset its state and the file was not reloaded. To what extent the full reset occured was unclear.
- New behavior - Causes reload of the file. This results in a complete reset including any internal state and will trigger the reload of all related files, such as FLV.

Loop - Has same meaning as in Flash 5 (which is different from normal MTSTimeElem property). However, now we just pass it to native Flash during initialization and let it deal with it on its own. Changing this property after SWF file is loaded is disabled.

FillBackground - May only be reset if FillBackgroundDynamic (see below) is true.

Inherited MTSTimeElem properties

Controlling Flash's Playing State

You can use normal MTSTimeElem properties strt, stop, stpc, runs, clps, rst_, rwnd, trgr, paus to start/stop/rewind/pause main (root) Flash movie. However, keep in mind that stopping the main Flash movie (just like in native Flash) does not necessarily stop video/audio playback. Therefore, it is advised to call some exported Flash function which will achieve the desired effect.

Flash's Time access and control

Normally we do not control Flash's time, letting it run at its own pace. One would only control it's state (see above). However, if you access time property, either for read or write, it will be converted to frames according to file's Frames Per Second (FPS).
Note that theoretically one can change FPS in Flash in runtime, but this is not taken into account - only the file's setting is used.
Also, as we use GotoFrame function, intermediate frames are skipped.
You can animate time for paused Flash movie.
tmap (TimeScale) should be supported if you animate time, but this is not tested.
pdir (PlayDirection) is not supported.

Properties of SWFView9 animator

Name	Mode	Type	Default	Description
BasePath	R/W	string		URL for reloading relative Path (below). Ignored if `Path` is absolute. Usually is set automatically as the position of enclosing MTX or HTML.
Path	R/W	string		The URL of the Flash file loaded by Animator. Could be relative to `BasePath`.
UseSWFStatus	R/W	boolean	false	If true, read/write of non-existing DOM property or calling non-existing function will cause failure. Else it will be ignored
Loop	R/W	boolean	true	Corresponds to native Flash embed parameter which tells if Flash has to go to first frame after it reaches last frame
SWF	R	object		Serves as root for accessing native Flash variables and functions. See Scripting
Version	R	real	0.0	The version of the Flash DLL loaded by Animator. Example: 9.0.
Reload	W	uint32		Setting this to "1" causes current movie to be reloaded. All related files like FLV are reloaded too.
Preload	R/W	boolean	false	Whether the Animator loads Flash file even if it is off.
FillBackground	R/W	boolean	false	Whether the Animator renders Flash file in opaque mode, filling in the transparent areas with the background color. May only be reset if "FillBackgroundDynamic" is true.
FillBackgroundDynamic	R/W	boolean	false	Whether the Animator allows FillBackground to be changed after initialization. May not be reset.
MinimumFlashVersion	R/W	string		Minimum version of Flash DLL required for the content, friendly-number form (eg, "9.0.115.0").
Width	R/W	uint32	0	The width of the Animator's target texture(s). Not required. Defaults to Flash movie size.
Height	R/W	uint32	0	The height of the Animator's target texture(s). Not required. Defaults to Flash movie size.
ForceFlashDimensions	R/W	boolean	false	Forces the Animator's target textures to the same dimensions of those of the Flash file. Equivalent to setting "Width" and "Height" to those values.
AutoInvertTargetAlpha	R/W	int32	1	Normally Flash would require `InvertAlpha="1"` for target texture. This parameter controls if this setting is automatically adjusted. 0 - off 1 - only for textures with alpha 2 - for all textures
ASVersion	R	uint32	0	The ActionScript version of the Flash file. 0 - invalid or unknown (movie is not loaded yet) 1 - Flash Version <= 5 2 - Flash Version <= 9 3 - Flash Version == 9 and is using AS3
FileVersion	R	uint32	0	The Flash version of the loaded Flash file.
Compose	R/W	boolean	false	If true, Flash will render on top of existing target. If false - will erase target texture with background color before rendering. Has meaning only for texture targets, for Pre-/Post- Animators it sort of is true always.
Render	R/W	boolean	true	Turns on or off rendering of Flash movie.
FlashVars	R/W	string		Used for setting native Flash variables. Same as Flash embed tag. Note that because it is in XML (MTX) file, it should be XML-escaped. therefore if you want to specify two variables, you have to write something like: `FlashVars="QAID=14445&QPAN=0"`
SWFWidth	R	uint32	0	The Width of the Flash file (stage).
SWFHeight	R	uint32	0	The Height of the Flash file (stage).
FullScreen	R	boolean	false	Whether the Animator is currently in full-screen mode.
UseFlashTime	R/W	boolean	true	If `false` - prevents animator from using `CurrentFrame*FPS` as Flash animator's time. Note that unless you explicitly animate or directly refer to `time` property, Flash time is not accessed.
DefaultProtocol	R/W	string	vetscript:	Default protocol to be used if none is specified. Possible values are vetscript: and javascript:. See Scripting
Scale	R/W	string	ExactFit	Same as Scale parameter for native Flash embed. Other valid values are `ShowAll, NoBorder, ExactFit, NoScale`. See Flash CS3 Documentation. Note, however, the defaults differ.
SAlign	R/W	string	[empty (= c)]	Same as SAlign parameter for native Flash embed. Valid values are `L, T, R, B`, etc, or any combination, as if native Flash. Note that the Align property is not supported, as it is not applicable to VMP embedding.

Functions of SWFView9 animator

Name	Type	Description
GetCurrentFrame()	int32	Returns current frame for the main timeline.
CallFunction(func_name, ...)	NIK_Variant	Call arbitrary function in Flash movie and return it's result.

Functions of Adobe Flash 9 native DLL exposed by SWFView9 animator

Complete description could be found on Adobe's site

GetVariable( varName ) - Returns the value of the Flash variable specified by varName. Returns null if the variable does not exist. The argument type is string.
SetVariable( variableName, value ) - Sets the value of the Flash variable specified by variableName to the value specified by value. The argument type for both arguments is string.
Rewind() - Goes to the first frame.
Play() - Starts playing the movie.
IsPlaying() - Returns true if the movie is currently playing.
StopPlay() - Stops playing the movie.
GotoFrame( frameNumber ) - Activates the frame number specified by frameNumber in the current movie. If the data for a requested frame is not yet available, the player goes to the last frame available and stops, causing unexpected results during playback. Use the PercentLoaded() method to determine if enough of the movie is available to execute the GotoFrame() method. The argument frameNumber is zero-based; that is, frameNumber is 0 for the first frame of the movie, 1 for the second frame, and so on. This differs from the Goto action within Flash, which begins at 1. The argument type is integer.

TotalFrames() - Returns the total number of frames in the movie.
PercentLoaded() - Returns the percent of the Flash Player movie that has streamed into the browser so far; possible values are from 0 to 100.
LoadMovie( layerNumber, url ) - Loads the movie identified by url to the layer specified by layerNumber. The argument type is integer for layerNumber and string for url.
Pan( x, y, mode ) - Pans a zoomed-in movie to the coordinates specified by x and y. Use mode to specify whether the values for x and y are pixels or a percent of the window. When mode is 0, the coordinates are pixels; when mode is 1, the coordinates are percent of the window. Pan does not pan beyond the boundaries of the zoomed-in movie. The argument type for all arguments is integer.
SetZoomRect( left, top, right, bottom ) - Zooms in on a rectangular area of the movie. The units of the coordinates are in twips (1440 units per inch). To calculate a rectangle in Flash, set the ruler units to Points and multiply the coordinates by 20 to get twips. (There are 72 points per inch.) The argument type for all arguments is integer.
Zoom(percent) - Zooms the view by a relative scale factor specified by percent. Zoom(50) doubles the size of the objects in the view. Zoom(200) reduces the size of objects in the view by one half. Zoom(0) resets the view to 100%. You cannot specify a reduction in the size of objects in the view when the current view is already 100%. The argument type is integer.

TPlay(target) - Plays the timeline specified by target. The argument type is string.
TStopPlay(target) - Stops the timeline specified by target. The argument type is string.
TCallFrame(target, frameNumber) - In the timeline specified by target, executes the action in the frame specified by frameNumber.
TCurrentFrame(target) - Returns the number of the current frame for the timeline specified by target. The frame number returned is zero-based, meaning frame 1 of the Flash movie would be 0, frame 2 would be 1, and so on. The argument type is string.
TGotoFrame(target, frameNumber) - For the timeline indicated by target, goes to the frame number specified by frameNumber. The argument type for target is string. The argument type for frameNumber is integer.
TCallLabel(target, label) - In the Timeline indicated by target, executes the action in the frame specified by the label frame label. The argument type for both arguments is string.
TCurrentLabel(target) - Returns the label of the current frame of the timeline specified by target. If there is no current frame label, an empty string is returned. The argument type is string.
TGotoLabel(target, label) - For the timeline indicated by target, goes to the frame label specified by label. The argument type for both arguments is string.
TGetProperty(target, label) - For the timeline indicated by target, returns a string indicating the value of the property specified by property. For property, enter the integer corresponding to the desired property. For a list of all properties and their corresponding integers,
TGetPropertyAsNumber(target, property) - Same as above, returns number
TSetProperty(target, property, value) - For the timeline indicated by target, sets the value of the property specified by property to the value specified by value, which can be a string or a number. For property, enter the integer corresponding to the desired property. For a list of all properties and their corresponding integers see Getting and setting properties.

Scripting

A comprehensive description of VMP Flash 9 scripting functionality will be included in the final Release Notes that will be out soon. The following is a brief description:

For all flash methods listed below, syntax and behavior should be exactly as described whether hosted by us or by the browser unless otherwise noted. However, when the flash movie is hosted by VMP, the functionality is extended by using either keywords or “protocols” (these protocols, and their syntax and functionalities will be described in detail below) to allow direct access to the VMP Scene DOM and VMP specific functionalities. By default “vetscript:” protocol is used, meaning that all commands will be executed by VETScriptInterpreter animator. It is possible to change default protocol:

<MTSTimeElem Name="vmp_to_flash" Type="SWFView9" Path="vmp_to_flash.swf" DefaultProtocol=”javascript:”/>.

This would be useful when swf file had some communication with HTML set up, but now has to be placed into MTX.

Protocols

vetscript: - (default) command will be executed by VETScriptInterpreter animator.
javascript: - command will be passed for execution to the browser.
vbscript: - Same as javascript:. Can't be set as default.
scene: - Try executing command in MTX terms ("MTSAssignProperty", "PostMessage", etc.). If command doesn't exist, try default protocol.
fscommand: - same as scene:, for backward compatibility.
mailto: - Brings up email program.
extern: - Internal use only
trace: - Print message to ContentDebugger.

Scripting Out

getURL(url:string, [window:string, [method:string)]: Loads a url into an existing window or provides target with optional parameter. Can be used to load SWF file into animator.
fscommand(command:string, [arguments:string) : void]: Default protocol is scene: regardless of animator setting. If it fails, then it will try to use default protocol.
extern.[MTSType].[Name].[Property]: (Viewpoint specific flash5-flash9 player only). Allows direct dot syntax access to VMP (mtx) scene DOM. Supports properties only (no function calls). Extern is slow and is not supported for AS3. Not recommended for new code.
ExternalInterface.call(functionName:String, arguments): (flash8-flash9) Used to call methods in VETScript or JavaScript and returns the return value of the called method. Also used to create aliases for callback methods in ActionScript. Use [#Protocols|Protocols] to specify which scripting engine to use.

Scripting In

SWF: (ActionScript DOM object: Viewpoint specific flash5-flash9 player only) Allows direct dot syntax access to SWF DOM. Works for properties and functions.
Javascript API. It is possible to control Flash player using VMP the same way as one can control it when hosted by HTML page:

<MTSSetProperty Target="vmp_to_flash. GotoFrame()" Value="3"/>

ActionScript Support

Flash movies using AS1 and AS2 do not need to be modified in order for the published swf to work.
Flash movies using AS3 need the following file added to the beginning of frame 1 code.

Scaling

A comprehensive description of VMP Flash 9 scaling functionality will be included in the final Release Notes that will be out soon. It will include the supported, as well as recommended Flash scaling methods and the differences between Flash directly embedded within the browser and Flash embedded within the VMP.

Flash 9 Full-screen support

Adobe introduced full-screen capabilities into their Flash 9 browser plug-in, in two incremental steps: version 9.0.28.0 for software mode, and version 9.0.115.0 for hardware-accelerated mode. Once full-screen mode is triggered, rendering of the Flash content is passed directly to the Flash DLL, thereby having the effect of full support for all of Flash 9's full-screen features. Additionally, the limitations of when this mode may be triggered, and how either mode is triggered, is a Flash/ActionScript issue, and is fully independent of the container (whether that be the browser or the VMP). The main difference between content designed for Flash-in-browser as opposed to Flash-in-VMP is that the VMP automatically enables the allowFullScreen property, so the content developer need not specify it in the mtx code. The full-screen mode applies to any manner of Flash content, whether it be SWF, FLV, etc, and not just video. The details of the H.264-video-specific hardware-acceleration have not yet been documented. It is yet to be determined, whether Flash will use hardware features such as NVidia's PureVideo to perform parts of the video decompression, in addition to scaling.

Please note, that the Flash DLL pre-fills the full-screen area with the background color of the Flash movie. Thus, anything behind the transparent pixels of the Flash file will not show through. To have a Superview-like effect, Flash in non-full-screen mode must be used within Superview, with the animator targeting a texture (of a 2d-layer) or set as a pre-animator or post-animator.

See Exploring full-screen mode in Flash Player 9, Flash Player:9:Update:Full-Screen Mode HW and Exploring Flash Player support for high-definition H.264 video and AAC audio for nice overviews of the technology, property definition, and samples. As stated above, less the one exception, these all apply to Flash 9 content embedded within the VMP scene.

top