Skip to content

The element and its options

The element also takes salign, wmode, bgcolor, base, quality and allownetworking. It has load(url | bytes) and destroy(), which gives back its GL context, audio and sockets. It fires load, error and fscommand events, and with Stage3D on, stagelayout as the SWF starts and whenever it sets its stage’s scaleMode or align (event.detail holds both): a page may size the element to the SWF’s own size while it asks for noScale, as an embedding at that size shows it.

Browsers hold a page’s sound until the user first clicks or presses a key in it, where Flash Player’s plug-in played it at once. When a SWF’s sound waits so, the element fires audioblocked and shows a “Click to unmute” button over the stage; a click on it, or Enter or Space, lets the sound play, as far in as a streamed soundtrack has gone meanwhile, and does not reach the SWF. A click or key on the SWF itself lets the sound play too, the SWF hearing it as usual. Either way the element fires audiounblocked, as it does when the SWF that held the sound is destroyed or another is loaded in its place; a SWF that plays no sound shows no button. Each element on a page shows a button of its own, whose click unmutes its own SWF. unmuteprompt="false" on the element, or configure({ unmutePrompt: false }) for the page’s elements, leaves the button out, for a page that shows its own: its click handler calls element.player?.audio?.resume(), which a browser allows only while it handles the user’s click or key. The desktop app’s window lets sound play at once.

A SWF goes full screen by setting Stage.displayState, as under Flash Player’s plug-in: only with allowfullscreen="true" on the element (allowfullscreeninteractive="true" for "fullScreenInteractive"), and only from a mouse or key handler, as the browser’s Fullscreen API asks too; otherwise the setter throws SecurityError #2152. The element then covers the screen, the stage placed by its scale mode, or its fullScreenSourceRect alone, fitted and centred. Esc leaves, and the SWF gets its FullScreenEvent either way. replaceFlash carries both parameters over. An AIR application needs neither attribute, but still the click. A page that makes the element full screen itself (element.requestFullscreen()) puts the stage in full screen too. configure({ fullScreen }) takes a full screen of the embedder’s own instead, as the desktop app’s window, which needs no click.

With Stage3D on, a back buffer may be from 32 to 16384 pixels a side in every profile, as Flash Player 32 and AIR 51 take one on a desktop GPU, so a SWF that sizes its back buffer to its stage plays on a 2K or 4K screen. maxBackBufferWidth and maxBackBufferHeight read 16384 whatever the GPU. Where the GPU allows less, the back buffer is drawn at the largest size it allows and stretched to the size asked for; AIR would read the GPU’s own limit there and refuse larger sizes. In the baselineConstrained profile AIR draws no back buffer larger than the stage (Error #3710, or #3723 for SWFs before version 30); swf2es draws it.

A back buffer configured with wantsBestResolution is drawn at the screen’s pixels: its size times Stage.contentsScaleFactor, which is the page’s devicePixelRatio (1 for an AIR application whose descriptor does not ask for <requestedDisplayResolution>high</requestedDisplayResolution>, as in AIR). backBufferWidth, backBufferHeight and drawToBitmapData then count those pixels, the scissor rectangle stays in stage pixels, and the canvas keeps its size on the page. The ratio holds the browser’s zoom too, which Flash kept apart as browserZoomFactor (1 here), so wantsBestResolutionOnBrowserZoom adds nothing; a best-resolution back buffer follows the ratio as the page is zoomed or moved to another screen, and must be cleared again. It costs the ratio squared in memory: a 1920 by 1080 back buffer at a ratio of 2 is 3840 by 2160, 33 MB for each of its colour, depth and stencil, and the canvas’s two buffers, about 130 MB, and 265 MB more in multisampled buffers at 4x antialiasing; one of 3840 by 2160 at a ratio of 2 is four times all that.

Every Stage3D profile is served, from baselineConstrained to standardExtended, requestContext3DMatchingProfiles taking the best asked for, as Flash does on a desktop GPU. The standard profiles run AGAL 2 and 3 programs (conditionals, derivatives, depth output and their larger register files), half-float textures and up to four colour outputs at once; the packed 16-bit formats work in every profile. Instanced drawing, which only AIR has, is not there yet.