PureBasic Forums - English

Introduction

To begin we will create a triangle and will post it with the screen. This first tutorial on 3d will enable us to approach:

• * The creation of a mesh
  * The creation of a texture
  * The creation of a material
  * The creation of an entity
  * Ambient lighting
  * The creation of a camera
  * The ?posting? of a 3D scene

Mesh

What the docs say:

• From English reference
  Meshs are 3D objects composed of many vertices (and triangles) which are linked together to make the final shape. A mesh can have an optional skeleton, with bones to allow realtime animation. A mesh can't be moved or displayed directly, but need to be used trough an entity.
  
  From my take on Comtois' quote of the French doc
  Meshs are 3D objects made up of triangles which are connected together to give the final form. A mesh can have a skeleton if it is animated, allowing realistic quality animations. A mesh cannot be posted directly into the 3D world, it must be encapsulated in a entity.

A triangle is defined by 3 "angles" or "points", these are the "vertices" (vertices plural, vertex singular). A vertex is defined by:

• * A position in X, Y and Z (#PB_Mesh_Vertex)
  * A normal (#PB_Mesh_Normal)
  * A color (#PB_Mesh_Color)
  * The U and V co-ordinates of a texture. (#PB_Mesh_UVCoordinate)

Only the position of the vertix is obligatory. The normal, the color and UV co-ordinates are optional. In this tutorial we will create a mesh by defining the position and the color of the vertices. ?The co-ordinates of the position compared to each other gives the reference marks of the mesh.? (Les coordonnées de la position se donnent par rapport aux repères du mesh)

This reference mark is independent of the reference mark of the 3D scene.

Code: Select all

;Création of a mesh 
#Mesh = 0  
CreateMesh(#Mesh, 200) ; 200 indicates the maximum dimension of the mesh
   
;Definition of Vertices
SetMeshData(#Mesh, #PB_Mesh_Vertex | #PB_Mesh_Color , ?SommetsTriangles, 3) ; Indicate the number of vertices

;Definition of Triangles
SetMeshData(#Mesh, #PB_Mesh_Face, ?IndexTriangles, 1) ; Advise the number of triangles.

In the above:
?SommetsTriangles is the address of the data area corresponding to the definition of the vertices.

In the first example one uses data, but it is also possible to use an ?array?table? or to allocate a ?memory?storage? block, to see examples, see below.

?IndexTriangles indicates the address of the data relating to the definition of the triangles - in our example there is only one triangle.

Code: Select all

IndexTriangles:
Data.w 2,1,0

Important: Note the .w for data, you must use Word data types.

To form a triangle it is necessary to indicate the index of the vertices in a precise order, in the reverse direction relative to the viewpoint (?camera?needles?!?points?) - the other face of the triangle will be invisible.

Try to cross 0 and 2:

Code: Select all

IndexTriangles:
  Data.w 0,1,2

By changing the order of the vertices, the triangle is not visible any more. Carry out the test! To see it again the camera would have to be placed behind. (?So that the visible face was seen?)

Code: Select all

CameraLocate(#Camera, 0, 0, -500); Position the camera

If one wanted to carry out rotations with our triangle it would thus be necessary to double the faces, so that our triangle is always visible regardless of the position of the camera.

Code: Select all

IndexTriangles:
  Data.w 2,1,0
  Data.w 0,1,2

And of course, do not forget to change the number of faces:

Code: Select all

;Definition of triangle
SetMeshData(#Mesh triangles, # PB_Mesh_Face?IndexTriangles, 2); indicate the number of triangles here

Texture

What the docs say:

• English:
  Textures are useful to have realistic looking meshes. It's possible to create a texture on fly (with regular 2DDrawing commands) or load it from disk. InitEngine3D() should be called successfully before using the Texture commands.
  
  From the French/tutorial:
  Textures make it possible for 3D objects to have a realistic aspect. Indeed, without textures the objects 3d would be of only one plain color. PureBasic makes it possible to create textures directly using the basic 2D tools (library/section 2DDrawing) or to load them from files.

To load a texture use the LoadTexture() command.

In this tutorial we will not use media, we must thus create our texture.

Code: Select all

;Creation of a texture
#Textures = 0
CreateTexture(#Texture, 64, 64)
;Create a fill/image in white in order to see/visualize the colors of the vertices
StartDrawing(TextureOutput(#Texture))
  Box(0,0, TextureWidth(#Texture), TextureHeight(#Texture), RGB(255, 255, 255))
StopDrawing()

It is a simple white square. For fun, change the color of the texture and observe the changes with ?posting?running?l'affichage?

Material

What the docs say:

• English:
  Materials are composed of one or several textures and sometimes of some colors. They are widely used by the other objects of the 3D world like the entities, billboards and particles to give them a skin.
  Each material has a lot a properties like the shading, ambient and specular color, etc. to allow realistic looking material like wood, water, glass and more.
  
  From French/tutorial
  The materials are made up of one or more textures and sometimes of colors. They are used by the other 3D objects such as the 'Entity', 'Billboards' and 'Particles' to give them a material (mainly a texture).
  Each material gathers a great number of properties such as lighting, the specular color and refraction, etc to make it possible for a material to resemble complex coatings like glass, water, wood...

Code: Select all

;Creation of a material
#Matiere = 0
CreateMaterial(#Matiere, TextureID(#Texture))
MaterialAmbientColor(#Matiere, # PB_Material_AmbientColors)

To see the color of the vertices defined previously, we must use the MaterialAmbientColor() command with the constant #PB_Material_AmbientColors.

You can try commenting out this command and observe what occurs. It is also possible to give a color to the material (for example MaterialAmbientColor(#Matiere, $FF00FF)), in this case the colors of the vertices will not be used any more.

The material management is a vast subject, especially since V4 makes it possible to use scripts. Perhaps one will return there in another tutorial. If you are impatient you can always throw an eye on the Doc. of ogre. To load a file script refer to the command Parse3DScripts().

Entity

What the docs say:

• English doc:
  Entities are objects composed of one mesh object and one material which can be freely moved and transformed in realtime.
  It's possible to share a mesh or a material between several entities, reducing memory consumption and saving CPU clocks.
  
  From the French/tutorial
  An Entity is an object made up of a mesh and a material which is capable of being moved and transformed in real time. It is possible to ?reuse?divide? the same Mesh between several Entities while using a different material for each Entity, thus reducing memory consumption and the use of the processor.

Code: Select all

;Creation entity
  #Entity = 0
  CreateEntity(#Entity, MeshID(#Mesh), MaterialID(#Matiere))

Ambient Lighting

If you find the 3D scene too dark, you can change the ambient color with the command:

Code: Select all

AmbientColor(Rgb(255, 255, 255))

One will see in another tutorial the utilisation of the lights, just know for now that it will be necessary to reduce the ambient light so that the effect of the added lights is perceptible. For example a dark gray light.

Code: Select all

  AmbientColor(Rgb(85, 85, 85))

Camera
What the docs say:

• English doc
  Cameras are used to display the 3D world. You can manage them like real life cameras, which means you can rotate, move, change the field of vision and more. At least one camera is absolutely required in order to render the world to the screen. Many cameras can be used at the same time with different positions and views to allow cool effects like: split-screen, rear view, etc
  
  French/Tutorial
  The cameras are used to move in the 3D world. It is possible to use them as real cameras which one can move, to carry out rotations, to change the angle of vision etc. At least one camera is necessary for effecting (rendering?) of the 3D world on a screen, but several cameras can be used at the same time to post(display?) the world under different angles of sight (rear view mirrors, Split-screen...).
  

For this tutoriel one is satisfied with only one camera

Code: Select all

 ;Creation of a camera, it is essential to see something
  #Camera = 0
  CreateCamera(#Camera, 0, 0, 100, 100); Creation of camera
  CameraBackColor(#Camera camera, #$$FF0000>); Blue prime coat
  CameraLocate(#Camera, 0, 0, -500); Position the camera
  CameraLookAt(#Camera, EntityX(#Entity), EntityY(#Entity), EntityZ(#Entity)); Orient/Direct the camera towards the entity

For the demonstration our camera occupies half of the screen in width and in height and to center it in this region one places it at 25% (screen widht? -v- region widht?) in from the left, and 25 % down from the top.
For a camera which occupies all the screen recopy this line:

Code: Select all

  CreateCamera(#Camera, 0, 0, 100, 100); Creation of a camera

First 3D program
This program uses data (for vertices positions and etc?)

Code: Select all

;PB 4.0 le 18/08/06

InitEngine3D()
InitSprite()
InitKeyboard()

OpenScreen(800, 600, 32, "Tutoriel 3D")  
 
;Création of the mesh  
#Mesh = 0  
CreateMesh(#Mesh, 200)
   
;Définition of the vertices
SetMeshData(#Mesh, #PB_Mesh_Vertex | #PB_Mesh_Color , ?SommetsTriangles, 3) ; Indicate number of vertices

;Définition of triangles
SetMeshData(#Mesh, #PB_Mesh_Face, ?IndexTriangles, 1) ; indicate the number of triangles

;Création of a texture
#Texture = 0
CreateTexture(#Texture, 64, 64) 

;{Remplissage de la texture en blanc pour visualiser les couleurs des sommets}
;Draw a box to use as the texture that gives visual/colour effect to the vectors / vertices?
StartDrawing(TextureOutput(#Texture))
  Box(0,0, TextureWidth(#Texture), TextureHeight(#Texture), RGB(255, 255, 255))
StopDrawing()
   
;Créate material
#Matiere = 0
CreateMaterial(#Matiere, TextureID(#Texture))
MaterialAmbientColor(#Matiere, #PB_Material_AmbientColors)
   
;Créate entity
#Entity = 0
CreateEntity(#Entity, MeshID(#Mesh), MaterialID(#Matiere))

;Add a caméra, indispensable if something is to be seen
#Camera = 0
CreateCamera(#Camera, 25, 25, 50, 50) ; Créate caméra
CameraBackColor(#Camera, $FF0000) ; Back color is blue
CameraLocate(#Camera,0,0,500) ; Position the caméra 
CameraLookAt(#Camera, EntityX(#Entity), EntityY(#Entity), EntityZ(#Entity)) ; Point/orient the caméra towards the entity 
   
Repeat

  ClearScreen(0)
           
  ExamineKeyboard()
 
  RenderWorld() ; Display the 3D world
  
  FlipBuffers()
       
Until KeyboardPushed(#PB_Key_All) 

DataSection

  SommetsTriangles:
   
    Data.f 0.0,100.0,0.0              ; Position vertex 0
    Data.l $FF0000                    ; Colour vertex 0 
    Data.f 200.0,-100.0,0.0           ; Position vertex 1
    Data.l $00FF00                    ; Colour vertex 1
    Data.f -200.0,-100.0,0.0          ; Position vertex 2
    Data.l $0000FF                    ; Colour vertex 2

  IndexTriangles:
    Data.w 2,1,0                      ; Vertices 2, 1 and 0 form a triangle

EndDataSection