google / marzipano

A 360° media viewer for the modern web.
http://www.marzipano.net
Apache License 2.0
2k stars 998 forks source link

Improve documentation on level selection #101

Open etki opened 7 years ago

etki commented 7 years ago

Hi! I'm trying out Marzipano, however, i got lost somewhere amidst level settings. It is quite clear that different levels represent different resolution tiling, however, it is not clear how particular level gets selected. All the demos on marzipano.net are immediately requesting level 3, however, if i try to reproduce the code, my Marzipano instance tries to fetch level 0, which is absent on the website (even though fallbackOnly is set to true for the first level, and faceSize = 4096 is used in view limiter); also it is not clear when and how Marzipano decides to switch levels. May ask you to document this behavior?

tjgq commented 7 years ago

The documentation on level selection is indeed lacking. Note that this is partly on purpose (we'd like users of the library not to rely too much on the details, since they might change in the future), but I agree that it should be better. Here's a rough overview.

As a general rule, Marzipano selects the smallest level that provides adequate resolution for the current view (the meaning of "adequate" is best understood by reading this comment) and loads tiles for that level only; there is no progressive loading of successively larger levels.

Zooming in or out, or changing the window size, might cause a new level to be selected. While the new tiles are loading, tiles from other levels that were loaded previously may be used to fill in gaps (this is called "fallback" in the source code). Levels marked fallbackOnly are only used as fallback, i.e., a larger level will eventually be loaded in their place.

Tours generated by the Marzipano Tool, as well as most of the demos, pin the first level (pinning means tiles are fetched automatically and kept in memory, so that they can serve as a fallback of last resort). This is controlled by the pinFirstLevel option passed to Viewer.createScene, and is probably the reason why you're seeing requests for level 0 tiles, even though level 3 is the appropriate one for your screen size.

etki commented 7 years ago

@tjgq Thank you!

tjgq commented 5 years ago

I will revisit this once #99 is fixed.