4. Table camera

Table global instanced by engine to access both camera 2D and 3D to the application. A camera have a scale to make easy to work on device.

Use getCamera method to get a camera 2DW supplying 2D string as parameter.
Use getCamera method to get a camera 3D supplying 3D string as parameter.

4.1. Camera 2D methods

4.1.1. camera 2d setPos

setPos(number x, number y)

Set position using x and y (2D world) position. This method consider camera’s scale.

Parameters

  • number – x position.

  • number – y position.

Example:

camera2D = mbm.getCamera('2d')
camera2D:setPos(0,0)
setPos(table renderizable)

Set position using a renderizable object position. This method consider camera’s scale.

Parameters

table – renderizable object.

Example:

camera2D = mbm.getCamera('2d')
tSprite = sprite:new('2d')
tSprite:setPos(500,300)
camera2D:setPos(tSprite)
setPos(vec2 vector)

Set position using a vec2 position. This method consider camera’s scale.

Parameters

table – vec2 vector.

Example:

camera2D = mbm.getCamera('2d')
tVec2 = vec2:new(100,20)
camera2D:setPos(tVec2)

4.1.2. camera 2d getRealPos

getRealPos

Return a vec2 which point to the real position (without scale) to the camera 2D.

Returns

vec2 - position to the camera 2D.

Example:

camera2D = mbm.getCamera('2d')
local posCamera2d = camera2D:getRealPos()
--change the position directly
posCamera2d.x = 0
posCamera2d.y = 10

4.1.3. camera 2d move

move(number x, number * y)

Move x and y units frames by seconds. This method consider the FPS.

Parameters

  • number – x position.

  • number – y position.

Example:

camera2D = mbm.getCamera('2d')
camera2D:move(100,50)

--this is equivalent
function loop(delta)
     camera2d.x = camera2d.x + (delta * 100)
     camera2d.y = camera2d.y + (delta * 50)
end
move(vec2 position)

Move x and y units frames by seconds using a vec2. This method consider the FPS.

Parameters

number – vec2 position.

Example:

camera2D = mbm.getCamera('2d')
vec = vec2:new(100,50)
camera2D:move(vec)

--this is equivalent
function loop(delta)
     camera2d.x = camera2d.x + (delta * vec.x)
     camera2d.y = camera2d.y + (delta * vec.y)
end

4.1.4. camera 2d scaleToScreen

scaleToScreen(number width, number height, *string axis)

Modify the camera 2D scale passing the expected screen width and screen height. The axis instruct to consider the x axis, y axis or both xy axis. The xy axis means that we want to stretch the screen to the client size. If not feed the axis the engine will decide the better axis based on screen size of client. The method to get the scaled size screen is getSizeScreen.

Parameters

  • number – width screen expected.

  • number – height screen expected.

  • string – axis to apply the scale.

Example:

camera2D = mbm.getCamera('2d')
--cause a stretch on screen
camera2d:scaleToScreen(1024,768,'xy')

--our application always will fit to the screen on y axis
camera2d:scaleToScreen(800,600,'y')

--our application always will fit to the screen on x axis
camera2d:scaleToScreen(1920,1080,'x')

Note

Scale to screen allows the application has the same ‘look’ for different screen size.

  • Let’s take a look at the table bellow understand better.

  • The camera 2D is set to resolution (width x height) (scaleToScreen) method.

  • The client width and client height is get by the method getSizeScreen (after set the expected width and height).

  • The scaled width and scaled height is the size adapted to the client.

  • The scale sx and scale sy is camera’s attribute.

width

height

axis

client width

client height

scaled width

scaled height

camera scale ‘sx’

camera scale ‘sy’

800

600

xy

800

600

800

600

1.0

1.0

x

800

600

1.0

1.0

y

800

600

1.0

1.0

1024

768

xy

800

600

1024

768

0.78125

0.78125

x

1024

768

0.78125

0.78125

y

1024

768

0.78125

0.78125

1920

1080

xy

1024

768

1920

1080

0.5333334

0.7111111

x

1920

1440

0.5333334

0.5333334

y

1440

1080

0.7111111

0.7111111

4.2. Camera 2D attributes

x, y [read / write]

Access the position x and y member from camera.

Example:

camera2D = mbm.getCamera('2d')
camera2D.x = 500
camera2D.y = 250
print('X:',camera2D.x,'Y:',camera2D.y)
sx, sy [read / write]

Access the scale sx and sy member from camera.

Example:

camera2D = mbm.getCamera('2d')
camera2D.sx = 1.5
camera2D.sy = 1.0
print('Scale X:',camera2D.sx,'Scale Y:',camera2D.sy)
'variable' [read / write]

Create a variable to read/write to camera. The type allowed is number, string, boolean, and table and function.

Example:

camera2D = mbm.getCamera('2d')
camera2D.myFloat = 1.5
camera2D.myInt = 5
camera2D.myString = 'Hello there!'
print('Accessing the variables myFloat:',camera2D.myFloat)
print('Accessing the variables myInt:',camera2D.myInt)
print('Accessing the variables myString:',camera2D.myString)

Tip

The variable is stored internally and belongs to the camera. So if we create a variable to the camera and load a new scene, then the variables will NOT be available because it is other scene. If you want to keep variable between scenes use setGlobal and getGlobal for that.

Error

It is important to understand that as all tables used in this engine, this table uses the first index from table to store the userdata pointing to the C++ class internally.

There is no mechanism to prevent to access the first index from camera. If you overload the userdata probably the program will crash.

Listing 4.1 Do not do this:
1 camera2D = mbm.getCamera('2d')
2 camera2D:setPos(100,20)
3 
4 print(camera2D[1]) -- read, okay will print userdata: 0x32958758b6a7 for example
5 
6 camera2D[1] = 2 -- Error, this will do your program crash!

4.3. Camera 3D methods

Use getCamera method to get a camera 3D.

4.3.1. camera 3d setPos

setPos(number x, number y, number z)

Set position using x, y and z (3D world) position.

Parameters

  • number – x position.

  • number – y position.

  • number – z position.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setPos(0,0,0) --origin
setPos(table renderizable)

Set position using a renderizable object position.

Parameters

table – renderizable object.

Example:

camera3D = mbm.getCamera('3d')
tMesh = mesh:new('3d')
tMesh:setPos(500,300,400)
camera3D:setPos(tMesh)
setPos(vec3 vector)

Set position using a vec3 position.

Parameters

table – vec3 vector.

Example:

camera3D = mbm.getCamera('3d')
tVec3 = vec3:new(30,20,50)
camera3D:setPos(tVec3)

4.3.2. camera 3d setFocus

setFocus(number x, number y, number z)

Set focus using x, y and z.

Parameters

  • number – x focus.

  • number – y focus.

  • number – z focus.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setFocus(0,0,0) --look at the origin
setFocus(table renderizable)

Set focus using a renderizable object position.

Parameters

table – renderizable object.

Example:

camera3D = mbm.getCamera('3d')
tMesh = mesh:new('3d')
tMesh:setFocus(50,120,20)
camera3D:setFocus(tMesh)
setFocus(vec3 vector)

Set focus using a vec3 position.

Parameters

table – vec3 vector.

Example:

camera3D = mbm.getCamera('3d')
tVec3 = vec3:new(5,15,0)
camera3D:setFocus(tVec3)

4.3.3. camera 3d setUp

setUp(number x, number y, number z)

Set ‘up camera’ using x, y and z.

Parameters

  • number – x ‘up camera’.

  • number – y ‘up camera’.

  • number – z ‘up camera’.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setUp(0,1,0) --default
camera3D:setUp(0,-1,0) --upside down
setUp(vec3 vector)

Set ‘up camera’ using a vec3 position.

Parameters

table – vec3 vector.

Example:

camera3D = mbm.getCamera('3d')
tVecNormal = vec3:new(0,1,0)
tVecUpsideDown = vec3:new(0,-1,0)
camera3D:setUp(tVecNormal) --default
camera3D:setUp(tVecUpsideDown) --upside down

4.3.4. camera 3d getPos

getPos

Get the camera’s position.

Returns

vec3 - camera’s position .

Example:

camera3D = mbm.getCamera('3d')
local posCamera = camera3D:getPos()
--move camera position to origin
posCamera.x = 0
posCamera.y = 0
posCamera.z = 0

4.3.5. camera 3d getFocus

getFocus

Get the camera’s focus vector.

Returns

vec3 - camera’s focus vector .

Example:

camera3D = mbm.getCamera('3d')
local focus = camera3D:getFocus()
--Look at the origin
focus.x = 0
focus.y = 0
focus.z = 0

4.3.6. camera 3d move

move(number x, number * y, number * z)

Move x, y and z units frames by seconds. This method consider the FPS.

Parameters

  • number – x position.

  • number – y position.

  • number – z position.

Example:

camera3D = mbm.getCamera('3d')
camera3D:move(50,60,70)

--this is equivalent
function loop(delta)
     camera3d.x = camera3d.x + (delta * 50)
     camera3d.y = camera3d.y + (delta * 60)
     camera3d.z = camera3d.z + (delta * 70)
end
move(string direction, number units)

  • Move to a specific direction. This method consider the FPS.

  • R move to the right direction.

  • L move to the left direction.

  • U move to up direction.

  • D move to down direction.

  • B move to back direction.

  • F move to forward direction.

Parameters

  • string – direction to move. Available: R, L, U, D, B and F.

  • number – units position.

Example:

camera3D = mbm.getCamera('3d')
--move to the right 100 FPS
camera3D:move('R',100)
getNormal(string direction)

  • Retrieve the normal from specific direction based on current camera 3d position.

  • R get the the right direction.

  • L get the the left direction.

  • U get the up direction.

  • D get the down direction.

  • B get the back direction.

  • F get the forward direction.

Parameters

string – direction Available: R, L, U, D, B and F.

Returns

vec3 - camera’s direction normal vector.

Example:

camera3D = mbm.getCamera('3d')
local tNormalRight = camera3D:getNormal('R')
print(tNormalRight.x)

4.3.7. camera 3d setFar

setFar(number far)

Set the zFar for 3D projection.

Parameters

number – far value. Default is 1000.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setFar(500)

4.3.8. camera 3d setNear

setNear(number near)

Set the zNear for 3D projection.

Parameters

number – near value. Default is 0.1.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setNear(2)

4.3.9. camera 3d setAngleOfView

setAngleOfView(number degree)

Set a angle of view for 3D projection.

Parameters

number – degree value. Default is 110.

Example:

camera3D = mbm.getCamera('3d')
camera3D:setAngleOfView(65)

4.4. Camera 3D attributes

x, y, z [read / write]

Access the position x, y and z member from camera.

Example:

camera3D = mbm.getCamera('3d')
camera3D.x = 100
camera3D.y = 200
camera3D.z = 300
print('X:',camera3D.x,'Y:',camera3D.y,'Z:',camera3D.z)
fx, fy, fz [read / write]

Access the focus fx, fy and fz member from camera.

Example:

camera3D = mbm.getCamera('3d')
camera3D.fx = 10
camera3D.fy = 15
camera3D.fz = 0
print('Looking at X:',camera3D.fx,'Y:',camera3D.fy,'Z:',camera3D.fz)
'variable' [read / write]

Create a variable read/write to camera. The type allowed is number, string, boolean, table and function.

Example:

camera2D = mbm.getCamera('2d')
camera2D.myFloat = 2.5
camera2D.myInt = 8
camera2D.myString = 'Hi there!'
camera2D.bValue = true
camera2D.tUser = {name = 'Mario' , address = 'my street'}
camera2D.fSayHello = function (self)
    print('Hello ', self.tUser.name)
end

print('Accessing the variables myFloat:',camera2D.myFloat)
print('Accessing the variables myInt:',camera2D.myInt)
print('Accessing the variables myString:',camera2D.myString)
print('Accessing the variables bValue:',camera2D.bValue)
print('Accessing the table tUser:',camera2D.tUser.name,camera2D.tUser.address )

camera2D:fSayHello() -- invoke the function passing self as first argument

Note

The variable is stored internally and belongs to the camera from current scene. The variable is lost when loaded a new scene.

4.5. User data acknowledgment

This table uses the first index to store the userdata C++ class internally. So, if you want to store some values to the table you must use from the second element as exampled bellow:

Listing 4.2 You can do this:
1 camera3D = mbm.getCamera('3d')
2 camera3D:setPos(10,10,10)
3 
4 camera3D[2] = 'my var'
5 
6 print(camera3D[2]) -- 'my var'

Error

It is important to understand that as all tables used in this engine, this table uses the first index to store the userdata pointing to the C++ class internally.

There is no mechanism to prevent to access the first index from camera. If you overload the userdata, probably the program will crash.

Listing 4.3 Do not do this:
1 camera2D = mbm.getCamera('2d')
2 camera2D:setPos(10,10)
3 
4 print(camera2D[1]) -- read, okay will print userdata: 0x44958588a6a8 for example
5 
6 camera2D[1] = 2 -- Error, this will do your program crash!