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.