Libs3D Library Shapes: Difference between revisions

From GiderosMobile
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 9: Line 9:
Here is the plan:
Here is the plan:
* start with a camera
* start with a camera
* a world to populate (scene)
** a world to populate (scene)
* some common 3D shapes (plane, cube, ...)
* some common 3D shapes (plane, cube, ...)
* light and shadows
* light and shadows
Line 61: Line 61:


<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
-- a color
ground:mapColor(0x9d7878) -- (color,[alpha=1])
-- a texture (diffuse)
-- a texture (diffuse)
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
Line 83: Line 79:
</syntaxhighlight>
</syntaxhighlight>


== More shapes ==
The Mesh3D class (''3DShapes.lua'') has other shapes you can use: '''D3.Cube''', '''D3.Sphere''', '''D3.Cylinder'''.
<syntaxhighlight lang="lua">
-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)
local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)
local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)
</syntaxhighlight>
== Lighting ==
The final touch is lighting (''3DLighting.lua'').
About lighting:
*''Lighting.setLight(x,y,z,a)'' sets the position of the light source (spotlight) and the amount of ambient light
*''Lighting.setLightTarget(x,y,z,d,f)'' sets the target of the light source. ''x,y,z'' is the position where the light is pointing at, ''d'' determines the projection distance when computing shadows (d gives the far plane, and the near plane is computed as d/16 internally). ''f'' is the FoV angle (actually the half angle), it determines the opening of your spotlight cone, and has a consequence on the shadow precision
*Only objects between d and d/16 in the light cone will cast shadows
*Select ''d'' wisely as it has an impact on shadow precision
*the lib uses a 1024x1024 shadow map
The light source position and ambient light.
<syntaxhighlight lang="lua">
-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
</syntaxhighlight>
The light target has a position and a projection distance plus a field of view (fov) angle.
<syntaxhighlight lang="lua">
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
local pd, fov = 3*8, 7*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
</syntaxhighlight>
When we added the shapes to the world, we gave the shapes the ability to receive light and shadows: '''D3.Mesh.MODE_LIGHTING''', '''D3.Mesh.MODE_SHADOW'''. We need to compute the shadow map.
<syntaxhighlight lang="lua">
Lighting.computeShadows(scene)
</syntaxhighlight>
'''And voilà'''!
[[File:ss_3DShapes.png]]
== Playground ==
'''The full code'''
<syntaxhighlight lang="lua">
application:setBackgroundColor(0x454545)
-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
local sw, sh = application:getContentWidth(), application:getContentHeight()
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)
-- we position the view (camera) and set its target
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])
-- we add the view (camera) to Gideros stage
stage:addChild(view)
-- we will add 3D shapes and models to a scene
local scene = view:getScene()
--scene:setAutoSort(true)
-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
ground:mapColor(0x9d7878) -- (color,[alpha=1])
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
-- we tell the shape to receive light and shadows
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
-- we add the shape to the scene
scene:addChild(ground)
-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)
local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)
local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)


'''...TO BE CONTINUED...'''
-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
local pd, fov = 3*8, 7*8 -- 5*8, 6*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
Lighting.computeShadows(scene)
 
-- game loop
stage:addEventListener(Event.ENTER_FRAME, function(e)
cube:setRotationX(cube:getRotationX()+8*8*e.deltaTime)
sphere:setRotationY(sphere:getRotationY()+9*8*e.deltaTime)
cylinder:setRotationY(cylinder:getRotationY()+10*8*e.deltaTime)
Lighting.computeShadows(scene)
end)
</syntaxhighlight>


== I am out 2 ==
== I am out 2 ==
...
Please have a look at [[Libs3D Library ShapesV2|the Shapes Library V2]].


You are strongly encouraged to mess with the code.
You are strongly encouraged to mess with the code.

Latest revision as of 03:58, 1 August 2026


Please note: there is a Shapes Library V2. We only keep this one for backward compatibility 🤷‍♂️

I am ready

As we have seen, to make more advanced 3D, Gideros has a bunch of helper files packed in the Library folder.

Here is the plan:

  • start with a camera
    • a world to populate (scene)
  • some common 3D shapes (plane, cube, ...)
  • light and shadows
  • playground

Copy the following two Library folders in your project assets folder:

  • 3dbase
  • luashader

The Camera

The camera is a Viewport with a perspective projection Matrix (helper file 3DView.lua). Let's add one:

application:setBackgroundColor(0x454545)

-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
local sw, sh = application:getContentWidth(), application:getContentHeight()
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)

You can position the view (camera) and set its target using the Viewport:lookAt function.

-- we position the view (camera) and set its target
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])

In order to display the content of the Viewport (camera) to the screen, we add it to Gideros stage.

-- we add the view (camera) to Gideros stage
stage:addChild(view)

The World (scene)

We will add all our 3D models to a scene. The scene is a simple Sprite and is part of the camera.

-- we will add 3D shapes and models to a scene
local scene = view:getScene()

Our first shape: a Plane

We are going to use the Plane shape (helper file 3DShapes.lua), this will be our ground.

-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
-- a color
ground:mapColor(0x9d7878) -- (color,[alpha=1])

Let's texture our plane, I picked this one: https://polyhaven.com/a/forrest_ground_01, Diffuse, 1K, JPG

-- a texture (diffuse)
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)

We tell the shape to receive light and shadows.

-- we tell the shape to receive light and shadows
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)

And we add the ground to the world (scene).

-- we add the shape to the scene (world)
scene:addChild(ground)

More shapes

The Mesh3D class (3DShapes.lua) has other shapes you can use: D3.Cube, D3.Sphere, D3.Cylinder.

-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)

local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)

local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)

Lighting

The final touch is lighting (3DLighting.lua).

About lighting:

  • Lighting.setLight(x,y,z,a) sets the position of the light source (spotlight) and the amount of ambient light
  • Lighting.setLightTarget(x,y,z,d,f) sets the target of the light source. x,y,z is the position where the light is pointing at, d determines the projection distance when computing shadows (d gives the far plane, and the near plane is computed as d/16 internally). f is the FoV angle (actually the half angle), it determines the opening of your spotlight cone, and has a consequence on the shadow precision
  • Only objects between d and d/16 in the light cone will cast shadows
  • Select d wisely as it has an impact on shadow precision
  • the lib uses a 1024x1024 shadow map

The light source position and ambient light.

-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)

The light target has a position and a projection distance plus a field of view (fov) angle.

local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
local pd, fov = 3*8, 7*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)

When we added the shapes to the world, we gave the shapes the ability to receive light and shadows: D3.Mesh.MODE_LIGHTING, D3.Mesh.MODE_SHADOW. We need to compute the shadow map.

Lighting.computeShadows(scene)

And voilà!

Playground

The full code

application:setBackgroundColor(0x454545)

-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
local sw, sh = application:getContentWidth(), application:getContentHeight()
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)

-- we position the view (camera) and set its target
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])

-- we add the view (camera) to Gideros stage
stage:addChild(view)

-- we will add 3D shapes and models to a scene
local scene = view:getScene()
--scene:setAutoSort(true)

-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
ground:mapColor(0x9d7878) -- (color,[alpha=1])
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
-- we tell the shape to receive light and shadows
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
-- we add the shape to the scene
scene:addChild(ground)

-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)

local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)

local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)

-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
local pd, fov = 3*8, 7*8 -- 5*8, 6*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
Lighting.computeShadows(scene)

-- game loop
stage:addEventListener(Event.ENTER_FRAME, function(e)
	cube:setRotationX(cube:getRotationX()+8*8*e.deltaTime)
	sphere:setRotationY(sphere:getRotationY()+9*8*e.deltaTime)
	cylinder:setRotationY(cylinder:getRotationY()+10*8*e.deltaTime)
	Lighting.computeShadows(scene)
end)

I am out 2

Please have a look at the Shapes Library V2.

You are strongly encouraged to mess with the code.

Bye for now!


Libs3D