Trying to understand letterbox and zoomEven scale

Solar2D General Questions/Discussion
#1

OK, say I have a game in landscape with a background.png image that is 1140x720 to cover the majority of mobile device screen sizes.

To my understanding after reading the Project Configuration Guide, it sounds like if I use:

  • scale = “letterbox”  then my background image will be resized automatically to fit the entire image into the device screen area. Meaning that either the top/bottom or left/side of the device screen will have nothing to show (no image content there).
  • scale = “zoomEven” then my background image will be resized automatically to fit the device screen with either the top/bottom or left/right sides of the image bleeding out of the display area of the device screen.

From what I read in the Understanding Letterbox Scalling It sounds like the opposite of what I understood about letterbox and zoomEven. It sounds like if “The background though is a bit bigger for the screen and has some extra width compared to screen size. Since the background is centered, you would actually not see some pixels to the sides.” which is done by using letterbox.

In the image below, am I wrong in thinking the orange dotted line is the background image and the black part is the visible area of the device screen?

Also, my background image is not really scaling unless I scale it myself manually:

local background = display.newImageRect(backgroundGroup, "images/background.png", 1140, 720); background:scale(display.contentScaleX, display.contentScaleY); background.x = display.contentCenterX; background.y = display.contentCenterY;
#2

Hi @elifares,

In the guide, the “orange dotted lines” you refer to indicate the Corona content area. Images are really separate from that… you can position them anywhere you like, essentially, even totally off screen.

The content area is more directly related to the APIs outlined here:

https://docs.coronalabs.com/guide/basics/configSettings/index.html#content-properties

Brent

#3

Hi @bjsorrentino,

So what does content refer to exactly? I looked at the APIs outlined in the link you provided but but if content width/height is NOT screen width/height nor the background image width/height then what is it exactly?

I will do a little more digging around and print() out each of the API calls to figure out what they mean exactly.

Cheers.

#4

@bjsorrentino

I was getting confused because I thought the the “orange dotted lines” content area included the scene background too. So if I have this template where the blue part is my scene background and the red box is my content area then the orange dotted line in the guide refers to my red outlined box correct?

#5

When you create a content area by specifying a width and height in config.lua, you are creating a virtual point system. Depending on your scale mode what this means varies the definition, but starting with “letterbox” keeps things simple.

Let’s say you define something simple like a width of 200 and a height of 300. A 1.5:1 or (3:2) aspect ratio is common for Corona apps. When you call display.contentWidth you will get 200 and display.contentHeight you will get 300, though if you’re app is landscape the numbers will be reversed.  This is the grid you have to work with. The config.lua is always discussed in “portrait” mode. But since you’re dealing with a landscape app, the rest of the conversation will cover how Corona handle’s it.

In letterbox mode, the short side, the 200 points will fill the screen vertically.  The device is most likely not going to be a 2:3 ratio device, so the 300 width will not fill the whole screen. There will be extra pixels on either side of the content area that are known as letterbox pillers.  If you don’t take the steps to fill these areas, you will get black bars.  Filling will be discussed later.

If you choose “zoomEven”, the entire content area will be enlarged so that the 300 point side fills the left/right edges. This will now push part of the screen off the visible screen depending on the aspect ratio.

I personally recommend that everyone use “letterbox”. Dealing with multiple aspect ratios is simple.  Make your background big enough to cover all aspect ratios. Until the Galaxy S8 and the iPhone X, that was pretty simple:

background width = 16 / 9 * yourContentWidth

background height = 4 /3 * yourContentHeight

Given a typical 320x480 content area that many use, this would make your background 570 x 360.  You would use display.newImageRect() and load it in at it’s actual size.  This will fill the screen. Some of it will be off screen depending on the device, but you won’t have black bars.

Rob

#6

Hi @elifares,

In the guide, the “orange dotted lines” you refer to indicate the Corona content area. Images are really separate from that… you can position them anywhere you like, essentially, even totally off screen.

The content area is more directly related to the APIs outlined here:

https://docs.coronalabs.com/guide/basics/configSettings/index.html#content-properties

Brent

#7

Hi @bjsorrentino,

So what does content refer to exactly? I looked at the APIs outlined in the link you provided but but if content width/height is NOT screen width/height nor the background image width/height then what is it exactly?

I will do a little more digging around and print() out each of the API calls to figure out what they mean exactly.

Cheers.

#8

@bjsorrentino

I was getting confused because I thought the the “orange dotted lines” content area included the scene background too. So if I have this template where the blue part is my scene background and the red box is my content area then the orange dotted line in the guide refers to my red outlined box correct?

#9

When you create a content area by specifying a width and height in config.lua, you are creating a virtual point system. Depending on your scale mode what this means varies the definition, but starting with “letterbox” keeps things simple.

Let’s say you define something simple like a width of 200 and a height of 300. A 1.5:1 or (3:2) aspect ratio is common for Corona apps. When you call display.contentWidth you will get 200 and display.contentHeight you will get 300, though if you’re app is landscape the numbers will be reversed.  This is the grid you have to work with. The config.lua is always discussed in “portrait” mode. But since you’re dealing with a landscape app, the rest of the conversation will cover how Corona handle’s it.

In letterbox mode, the short side, the 200 points will fill the screen vertically.  The device is most likely not going to be a 2:3 ratio device, so the 300 width will not fill the whole screen. There will be extra pixels on either side of the content area that are known as letterbox pillers.  If you don’t take the steps to fill these areas, you will get black bars.  Filling will be discussed later.

If you choose “zoomEven”, the entire content area will be enlarged so that the 300 point side fills the left/right edges. This will now push part of the screen off the visible screen depending on the aspect ratio.

I personally recommend that everyone use “letterbox”. Dealing with multiple aspect ratios is simple.  Make your background big enough to cover all aspect ratios. Until the Galaxy S8 and the iPhone X, that was pretty simple:

background width = 16 / 9 * yourContentWidth

background height = 4 /3 * yourContentHeight

Given a typical 320x480 content area that many use, this would make your background 570 x 360.  You would use display.newImageRect() and load it in at it’s actual size.  This will fill the screen. Some of it will be off screen depending on the device, but you won’t have black bars.

Rob