kripken/emscripten — pull request #835 by MichaelRiss (2013-02-05 18:42:01+00:00)
Title: Improved Fullscreen handling (incoming branch version)

I'm not sure that rebasing my pull request on the incoming branch made reading the diff easier, I get tons of changes in 71 files - far more than I touched ...
Anyway, hopefully on your side the diff looks better/easier to read.

I attach the relevant notes again:

The ones specifically for you and for merging:
- You may want to review the requestFullScreen function. I extended the requestFullScreen function with extra parameters that have default values. Therefore it should be compatible to existing code while offering the new functionality. Still, you may want to refactor the code to comply with your API guidelines/philosophy.
- You should review my changes to shell.html . Instead of one button there are now 4 buttons to demonstrate the different ways to enter fullscreen mode. This version is primarily directed to you, so that you can choose which version(s) you want to pick as standard fullscreen button(s).

The ones describing the changes in general:
- the requestFullScreen function now has two boolean arguments: "doLockPointer" and "doResizeCanvas"
- when using "doResizeCanvas", the SDL application gets notified via the "SDL_VIDEORESIZE" event of the new resolution, the old resolution setting is saved and gets restored when the canvas returns to windowed mode
- when setting "doLockPointer" to false the mouse pointer remains visible in fullscreen mode and allows e.g. RTS (Real Time Strategy) type games
- the SDL application can check via the "SDL_FULLSCREEN" flag in the flags field of the SDL_Surface struct whether the canvas is currently in fullscreen mode or not.
- depending on the browser the SDL application can switch out of the fullscreen mode with the "SDL_WM_ToggleFullScreen(SDL_Surface*);" call (currently chrome supports it, firefox does not)
- Also, the requestFullScreen has been fixed to avoid repeated adding of the event listeners every time requestFullScreen is called.
- src/shell.html got changed to demonstrate all variants to switch to fullscreen mode

Note:
Due to the security model of web browsers, the SDL model cannot be
fully supported.

What is not possible?

- Initiating the switch to fullscreen from the SDL application.
- Initiating the pointer lock from the SDL application when not in fullscreen mode

How to work around the limitations?
All the actions that cannot be initiated by the SDL application have to be
initiated by the web browser instead.

A good practice should be to start the application in windowed mode and
have a button situated close to the canvas which switches the canvas into
fullscreen mode and also changes the canvas size to fullscreen resolution.
This way, the SDL application receives a SDL_VIDEORESIZE event and can
check in the even handler whether it is now in fullscreen mode and take
further actions.
When leaving fullscreen mode the old windowed canvas resolution gets
restored and triggers another SDL_VIDEORESIZE event which - again - can be
used to adapt the application to windowed mode.