[android] GeckoView Display/Session split

Jim Chen nchen at mozilla.com
Tue Nov 7 18:40:46 UTC 2017

Hi all,

The next phase in GeckoView development will involve the
Display/Session split (bug 1415252; see below for a description of
this work). The first step of that process landed in bug 1413698,
which introduced GeckoSession.

GeckoSession contains most of what used to be in GeckoView, so the
most significant change for developers is switching from using
GeckoView APIs to using the same APIs in GeckoSession. See [1] for how
that was done for geckoview_example. Other related changes include
renaming GeckoViewSettings to GeckoSessionSettings, and moving
GeckoView listener/delegate interfaces to under GeckoSession.

Going forward, the GeckoDisplay interface will be added, and core
functionality will be implemented in GeckoSession. The GeckoView class
itself will essentially become a convenience class for using
GeckoSession with a GeckoDisplay in the form of

There are still many details to be worked out, such as how to handle
input and how to support the dynamic toolbar feature. Please comment
if you have any questions or thoughts.


[1] https://hg.mozilla.org/mozilla-central/diff/1bb6b4ff9df2/mobile/android/geckoview_example/src/main/java/org/mozilla/geckoview_example/GeckoViewActivity.java#l1.49

Display / Session Split

Although GeckoView promises similar features and abilities to other
web components, such as the built-in Android WebView, we have an
opportunity to give Gecko some additional flexibility which will make
it suitable for solving a larger set of problems.

You can think of a web component as having two main parts. The
Display, or frontend, is what’s responsible for getting the web
content on the screen and interacting with the user. The Session, or
backend, communicates with the Display and takes care of the heavy
lifting. This is where the web engine lives, including the JS runtime,
DOM, layout, networking, etc. Often these two pieces are conflated for
ease of use or implementation simplicity, but for GeckoView we would
like to make them explicitly separate.

Gecko needs an Android Surface in order to start the compositor and
composite web content. There are several ways to get a Surface on
Android, all with their own advantages and designed use cases. If we
decouple the Display from the Session, we can allow any of these
methods to be used, enabling Gecko content shown in a variety of
different ways. Examples:

* SurfaceView for high-performance, untransformed output on the screen.
* TextureView for transformed output, useful for creating transitions
and animations.
* SurfaceTexture to show Gecko output in an OpenGL scene, like a game
or a VR/AR environment.
* MediaCodec to stream Gecko’s output to a video encoder.
* No Surface at all (or a dummy one) for a headless mode.

A Display would use any of the above methods to create an Android
Surface and give it to the Session.

This is a tremendous advantage over traditional monolithic approaches
(like Android WebView), and will let Gecko participate in new and
innovative uses of the web on Android.

You can basically think of a Session as a Java interface to the
<browser> XUL element or a nsDocShell. It therefore exposes a similar
API. The Session will be the entry point for loading a new URL,
navigating within the history, reloading a page, etc. It will also
allow the app to set delegate instances which allow Gecko to notify
the app of things like page load progress or to show UI like alert()

Initially we will have a 1:1 relationship between a Session and a
Display, but there shouldn’t be too many hurdles if we want to have
multiple displays per Session. This would allow you to, for instance,
view a page on the phone screen and simultaneously encode the output
to a video stream.

Display instances are expected to be very lightweight, with their only
responsibility being to create a Surface in some way and hand it to
the associated Session instance. They can optionally handle user
input, handing that off to the Session as well. An important point is
that even though each Session may have only one attached Display, it
is possible for that Display to change at any point. This means you
can have the same Session displayed in several different Activities
using any of the above means during the lifetime of the Session. For
example, you could have a 2D browser that transforms into a 3D one
when the user puts on their VR or AR headset.

Session lifetimes would be controlled by the app itself and not that
of any Display or Android Activity. They would, however, be restricted
by the lifecycle of the containing process.

More information about the mobile-firefox-dev mailing list