Gecko:Fullscreen API

(WIP)

This page is for documenting our Fullscreen API implementation.

Resources

• Fullscreen API spec
• Fullscreen design from :Verdi also includes some background info

Basic Control Flow

The flow of how Fullscreen API works is a bit complicated because we want to change the state of the document after the window enters or leaves fullscreen, so that we can:

1. provide a stable viewport size when we notify the content, and
2. insert fullscreen transition there.

The flow is different for non-e10s, e10s, and the browser element, because we need to go across the process boundary in later cases.

Most of this part is implemented in Bug 1161802.

Non-E10S

Entering Fullscreen

1. the page calls Element.requestFullscreen() (Element::MozRequestFullScreen())
2. (async) calls nsDocument::RequestFullscreen()
3. calls nsGlobalWindow::SetFullScreenInternal()
4. calls widget to enter fullscreen
5. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window enters fullscreen
6. calls nsIDocument::HandlePendingFullscreenRequests()
7. change the document state in nsDocument::ApplyFullscreen()

Exiting Fullscreen by Content

1. the page calls document.exitFullscreen() (nsDocument::MozCancelFullScreen())
2. calls nsDocument::RestorePreviousFullScreenState()
3. calls nsGlobalWindow::SetFullScreenInternal()
4. calls widget to leave fullscreen
5. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window exits fullscreen
6. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

Exiting Fullscreen by User

(usually via escape key)

1. in PresShell::HandleEventInternal()
2. calls nsIDocument::AsyncExitFullscreen()
3. (async) calls nsGlobalWindow::SetFullscreenInternal()
4. then same as above...

Exiting Fullscreen Unexpectedly

(page closure / navigation / fullscreen element removal)

1. two cases:
   • for page closure and navigation, nsDocument::OnPageHide()
   • for element removal, Element::UnbindFromTree()
2. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
3. (may async) calls nsGlobalWindow::SetFullscreenInternal()
4. calls widget to leave fullscreen

E10S

Entering Fullscreen

1. in the content process:
   1. the page calls Element.requestFullscreen() (Element::MozRequestFullScreen())
   2. (async) calls nsDocument::RequestFullscreen()
   3. dispatches MozDOMFullscreen:Request event to the chrome
   4. tab-content.js sends async message "DOMFullscreen:Request"
2. in the parent process:
   1. browser-fullScreen.js calls nsDocument::RequestFullscreen()
   2. calls nsGlobalWindow::SetFullScreenInternal()
   3. calls widget to enter fullscreen
   4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window enters fullscreen
   5. calls nsIDocument::HandlePendingFullscreenRequests()
   6. change the document state in nsDocument::ApplyFullscreen()
      • this step also dispatches MozDOMFullscreen:Entered to the chrome
   7. browser-fullScreen.js sends async message "DOMFullscreen:Entered"
3. in the content process
   1. tab-content.js calls nsIDocument::HandlePendingFullscreenRequests()
   2. change the document state in nsDocument::ApplyFullscreen()

Exiting Fullscreen by Content

1. in the content process:
   1. the page calls document.exitFullscreen() (nsDocument::MozCancelFullScreen())
   2. dispatches MozDOMFullscreen:Exit event to the chrome
   3. tab-content.js sends async message "DOMFullscreen:Exit"
2. in the parent process:
   1. browser-fullScreen.js calls nsDocument::RestorePreviousFullScreenState()
   2. calls nsGlobalWindow::SetFullScreenInternal()
   3. calls widget to leave fullscreen
   4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window exits fullscreen
   5. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
      • this step also dispatches MozDOMFullscreen:Exited to the chrome
   6. browser-fullScreenAndPointerLock.js sends async message "DOMFullscreen:CleanUp"
3. in the content process
   1. tab-content.js calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

Exiting Fullscreen by User

Since user always uses the chrome to exit fullscreen

• The parent process part is the same as Non-E10S / Exiting Fullscreen by User
• The content process only has the last step in E10S / Exiting Fullscreen by Content above

Exiting Fullscreen Unexpectedly

(navigation / fullscreen element removal)

1. in the content process:
   1. two cases:
      • for navigation, nsDocument::OnPageHide()
      • for element removal, Element::UnbindFromTree()
   2. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
      • (may async) this step also dispatches MozDOMFullscreen:Exited to the chrome
   3. tab-content.js sends async message "DOMFullscreen:Exit"
2. in the parent process:
   1. browser-fullScreen.js calls nsDocument::RestorePreviousFullScreenState()
   2. calls nsGlobalWindow::SetFullScreenInternal()
   3. calls widget to leave fullscreen
   4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window exits fullscreen
   5. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

Transition

This part is implemented in Bug 1160014.