contentWidth or actualContentWidth?

Can someone explain the difference between “display.contentWidth” and “display.actualContentWIdth” and which one should I use when positioning my objects.

https://docs.coronalabs.com/guide/basics/configSettings/index.html

Its basically because the different ways of scaling affect the ‘content’ area of your app, which is different to the actual screen size.

e.g.: When letterboxed, your app may have x by y but the real screen estate could be slightly different - think about the black bars on a letterboxed movie screen.

The same can apply to other areas, I believe one case is the area around the iPhone X notch. The content area would not include the ‘ears’ either side of the notch but actualContent would do.

I always use actualContentNNN because it tells me where I can render in useful Corona pixels, without accidentally having screen which is blank or bits poking out into the letterboxed bars/ears etc. Its important to remember about the situations like the notch, of course.

What you are saying makes sense, but what about “display.safeScreenOriginX”?

The simplest explanation is this:

display.contentWidth is the value you set for width in your config.lua. The same for display.contentHeight.  These will not changed based on device.  

display.actualContentWidth, Height will changed based on device. It will take the actual pixel width/height of the device, scale it to your defined content area and give you the device size in your content units.

Example:  width = 320, height = 480.  The iPhone 5 is a 640x1136 pixel device.  Pixel Width / Content width = 2, so actualContentWidth would be 320, actualContentHeight = 568.  

Since your content area will likely be centered on the screen, by default, you can use actualContentWidth/height to find the right and bottom edges.  Because of the centered area, 0, 0 will likely not be the left, top corner. That’s where display.screenOriginX, Y comes into play. These represent the left, top corners.

The iPhone X’s notch creates a unique challenge to developers.  display.actualContentWidth and Height will be the measure of the full size of the screen including the notice. Your content area will still be centered on the screen and the rules with actualXX and screenOriginNN are the same. Your background should fill the whole area.  You can use display.safeOriginX, Y to be the virtual left, top of the screen where you can put UI elements and keep them out of the notch area.

Rob

Nice explanation @Rob.

Thanks @Rob for answering.

I did a little test where I position a rectangle on the screen using the iPhone 6 simulator and the content in config.lua is set to:

width = 320,

height = 480, 

24488za.png

Here the X position  = display.contentWidth

prints ( 480 )

33bifbl.png

Here the X position = display.actualContentWidth

prints ( 569.17333984375 )

As you can see, neither of this values is giving me the desired result I need to position the object at the far right of the screen where only half of its body is showing.

Ironically, the Y value for both “contentHeight” and “actualContentHeight” is giving me the desired result. And they both print the exact same position ( 320 )

The orientation is set to “landscapeRight” and when I change it to “portrait” the problem becomes the height instead of the width. 

All Corona objects, by default are centered. That is .x and .y are the center of the object, so if you position a rectangle at display.actualContentWidth, half of it will be off screen.

There are two solutions. You can either adjust your .x to display.actualContentWidth - object.width/2 or you can learn about anchor points. Anchor points allow you to change the default position of .x and/or .y to be any point in the rectangle.  You can do something like:

local box = display.newRect( display.actualContentWidth, display.contentCenterX, 50, 50) box.anchorX = 1

or

local box = display.newRect( display.actualContentWidth - 25, display.contentCenterX, 50, 50)

Rob

I understand that, and as you can see in the image above, that is not the case. I stated in my post above that I want to position the object at the far right of the screen where only half of its body is showing. Obviously, display.actualContentWidth doesn’t do that.

Can you post your config.lua?  And your object creation and positioning code?

    local rect = display.newRect( sceneGroup, 0, 0, 32, 32 )     --rect.x = display.actualContentWidth   -- doesn't show on the screen rect.x = display.contentWidth -- like the image above rect.y = display.contentCenterY 

application = { content = { width = 320, height = 480,  scale = "letterbox", fps = 30, --[[imageSuffix = {    ["@2x"] = 2,    ["@4x"] = 4, }, --]] },}

Try:

rect.x = display.actualContentWidth + display.screenOriginX 

Because your content area is centered and there is extra space on both sides. Let’s continue to use the iPhone 5 as an example with your landscape app.  Your content area is 480 points. The actual screen width is 568. That means there are 88 more points than your content area. With your content area centered, that means 44 points are left of the content area and 44 points tot he right of the content area. Because the content area is already shifted 44 points to the right, you need to add the screenOriginX value (in this example -44) to shift those right edged items back to where you want them.

Rob

1-Why doesn’t the content area automatically fill the screen? is it because of the “letterbox” scaling option?

2- Why do I have to compensate for the width and not the height? it gets positioned correctly on the y axis with no extra calculations

object.x = display.actualContentWidth + display.screenOriginX

object.y = display.actualContentHeight – no extra calculations

14kwbaw.png

3- object.x = 0

243lppz.jpg

It’s just weird that “x = 0” is not the leftmost position on the screen, I have to use “screenOriginX” to get it right

@Abdo23

Have you looked at SSK or my collection of answers? https://github.com/roaminggamer/RG_FreeStuff
 
SSK exposes easy to use left, right, top, bottom, … variables:
 
See the list:
https://roaminggamer.github.io/RGDocs/pages/SSK2/globals/
 
This is how they are calculated: https://github.com/roaminggamer/SSK2/blob/master/ssk2/core/variables.lua
 
Or you can use less precise but still accurate code I often include in my many examples:

local w = display.contentWidth local h = display.contentHeight local fullw = display.actualContentWidth local fullh = display.actualContentHeight local centerX = display.contentCenterX local centerY = display.contentCenterY local unusedWidth = fullw - w local unusedHeight = fullh - h local left = centerX - fullw/2 local top = centerY - fullh/2 local right = centerX + fullw/2 local bottom = centerY + fullh/2

PS - Some of these variables are redundant now (over the years Corona has added more display.* fields with useful values), but I still keep mine because I’m used to using them.

PPS - All of my calculations assume you have not modified the screen origins (something I never do).
 

You can easily make 0 the left most side of the screen by changing the xAlign value to “left” instead of the default “center”. If you do that, then you wouldn’t need to add screenOriginX to your positioning.  However, this will break display.contentCenterX, Y because it shifts the content area to the left. You can always make your own centerX, centerY values by doing:

local centerX = display.actualContentWidth / 2

for instance.

Most people center the content area so that play is consistent across all devices. If you play on a taller device like a Galaxy S8 or an iPhone X, you will have your play area shifted even more left, but for your use you might find that works better for you.

And yes, this is an effect of using “letterbox”.  You may also find that “zoomEven” might work better for you. 

Rob

@roaminggamer

Thanks for your help. I took a look at SSK and it seems to have some useful stuff in it. But I couldn’t find some sort of documentation so I can get a better idea what kind of helpful functions it has and how to use them. Maybe you should do a video showing some of the stuff in there. 

@Rob Miracle

Thanks for your help and patience. I think I will stick with the default align value and do the calculations for positioning. 

@Abdo23,

Docs: https://roaminggamer.github.io/RGDocs/pages/SSK2/

I’m sure I linked this above?  What more were you hoping for?  

https://docs.coronalabs.com/guide/basics/configSettings/index.html

Its basically because the different ways of scaling affect the ‘content’ area of your app, which is different to the actual screen size.

e.g.: When letterboxed, your app may have x by y but the real screen estate could be slightly different - think about the black bars on a letterboxed movie screen.

The same can apply to other areas, I believe one case is the area around the iPhone X notch. The content area would not include the ‘ears’ either side of the notch but actualContent would do.

I always use actualContentNNN because it tells me where I can render in useful Corona pixels, without accidentally having screen which is blank or bits poking out into the letterboxed bars/ears etc. Its important to remember about the situations like the notch, of course.

What you are saying makes sense, but what about “display.safeScreenOriginX”?

The simplest explanation is this:

display.contentWidth is the value you set for width in your config.lua. The same for display.contentHeight.  These will not changed based on device.  

display.actualContentWidth, Height will changed based on device. It will take the actual pixel width/height of the device, scale it to your defined content area and give you the device size in your content units.

Example:  width = 320, height = 480.  The iPhone 5 is a 640x1136 pixel device.  Pixel Width / Content width = 2, so actualContentWidth would be 320, actualContentHeight = 568.  

Since your content area will likely be centered on the screen, by default, you can use actualContentWidth/height to find the right and bottom edges.  Because of the centered area, 0, 0 will likely not be the left, top corner. That’s where display.screenOriginX, Y comes into play. These represent the left, top corners.

The iPhone X’s notch creates a unique challenge to developers.  display.actualContentWidth and Height will be the measure of the full size of the screen including the notice. Your content area will still be centered on the screen and the rules with actualXX and screenOriginNN are the same. Your background should fill the whole area.  You can use display.safeOriginX, Y to be the virtual left, top of the screen where you can put UI elements and keep them out of the notch area.

Rob

Nice explanation @Rob.