This is my first tuto ever, so please tell me is something is unclear, or ununderstandable.
New tuto using the new GCORE and final version !

I puting this here, to don't make confusion with other.


First of all, please download the file attached to this post, (not in the GLib main thread, 'cause I didn't update it) (GCORE).
Last version is 2.0 omega
Place it preferably in archive : warning ! this file is pretty huge (6400 bytes !!).


I THE BASIS

Let's create a rotating cube !

First of all, include the GCORE prog inside of your axe source :

prgmGCORE

Once you did this you have access to all the GLib functions.


We need to define the 3D coordinates of each point of the cube, so we can rotate and display them afterwards.
Those points are just a bunch of data, so no real explanations are needed here :
Data(40r,-40r,40r)->GDB1
Data(40r,40r,40r
Data(-40r,-40r,40r
Data(-40r,40r,40r
Data(40r,-40r,-40r
Data(40r,40r,-40r
Data(-40r,-40r,-40r
Data(-40r,40r,-40r

Just remember that a 3D point is always defined as X,Z,Y using the standard 3D axis (X goes from left to right, Y from down to up and Z from near to far). Each coordinate takes 2 bytes, so don't forget the ^r.

By default GLib has no camera defined. So we must specify what type of camera we want to use.
In this example, I want to be able to rotate my cube : this is a GMODELVIEW camera (I don't want the camera to move, only the model to rotate). If we actually wanted to have a worldview (fps mode) camera, we would use the °GWORLDVIEW constant.

The function to define a camera is :

GNewCam(pointer to camera)
.Destroys r1

**But but but .... I don't know how to create my camera, and I need a pointer to it !
STOP don't worry, GLib provides two pointers to some really basic cameras ! These are the °GMODELVIEW and °GWORLDVIEW cameras.

So I just give one of those pointers to the function and my new camera is created :

GNewCam(°GMODELVIEW)
Glib also need a special structure, allowing easy vertex processing/clipping. It's called a VBO : vertex buffer object. Basically, it's just a ram area.
You need at the begining of your program to generate such structure :

This is the command used :
GGenVBO(size,data_to_match)
.destroy r1,r2
your size is the number of vertices you want to have.
data_to_match is the raw (not processed) vertices coordinates (here it's GDB1)
It also set the current VBO to the one created , so it will be used by all other command.

The function return a special value, that you have to store somewhere : it's the VBO id.
We now have this :

GGenVBO(8,GDB1)->G
.I used G, but you can used any way to save this value


Now we can start the main loop, with 3D calculations :

While 1
GUpdateVBO(G,0,7)

this piece of code "update" (transform the vertices) for the specified VBO. You can see that we are passing the id we have previously store.
0 and 7 are the start and the end of vertices we should transform. Here it transform from the vertx 0,...., to the vertx 7 (the last one)

And now we want display our points.
GLib provide the
GVBOPoint(id_vertex)
.destroy r1
function to retrieve a point from VBO. It's store the x-coord and y-coord on screen to GScreenX and GSreenY var (alias OP1 and OP1+2)
It also return in hl a clipping information : 0 if the point is visible, anything else (=/= from 0)

We can now write this :
For(M,0,7)
GVBOPoint(M)
!If
Rect(GScreenX,GScreenY,2,2
End
End

the code loop from the first vertice, to the last one, retrieve on screen coordinate and then disp it if it is visible.


We need now to handle the arrow keys, so we can rotate our cube. GLib provides an in-built function, which handles everything (life is beautiful isn't it  )

It's the GGetkey function.
The call is:
GGetkey()

End of the code :

GGetkey()

DispgraphClrdraw   // we want to have something on screen !
EndIf getkey(15) // stop the While loop if [clear] is pressed


Now time to compile it ... aaaaaaaaaand ...



It works !

II Let's put some line


Well, let's take the previous code we used. He only display dot point, that not super funny. So let's put some line in there !!
In fact, there is almost nothing more to add to your code.
I want to display line, and possibly clipped lines between them. We don't want to draw point, so the previous for() loop is useless.

GLib provide one function for this :
GClipLine(ID_vertex1,ID_vertex2)
.destroy r1 to r6
This is assuming that a VBO has been set.

We need however to know what vertices will be linked with. So let's create a list of ID's. Just to remember though :

Data(40r,-40r,40r)→GDB1    .vertex ID 0
Data(40r,40r,40r           .vertex ID 1
Data(-40r,-40r,40r         .vertex ID 2
Data(-40r,40r,40r           ...
Data(40r,-40r,-40r
Data(40r,40r,-40r
Data(-40r,-40r,-40r
Data(-40r,40r,-40r

The link between vertices will be handle by an for loop and a constant list (containing the correct vertex ID to link)

so we now have :
Data(0,1,2,3,4,5,6,7)->°LinkList
Data(0,2,2,4,4,6,6,0
Data(1,3,3,5,5,7,7,1

and :
For(M,0,11)    .there is 12 line to draw in a cube
GClipLine({M*2+°LinkList},{M*2+1+°LinkList}
End

combining all of this , aaaaaaaaand  (yes I like big and) :



well I fail in the link data list --'
exercice : find the right data list :p

the whole code, as ever :


correction of the exercice :


III Shaders (part 1)

you may wonder what is a shader, and what you can do with it. In fact, the shader is a way to override the static pipeline of the 3D calculations. You are able then to do a lot of thing with it. However, some vars, (r3 to r6) musn't be used inside shader functions, due to GLib using these.

Well, anyway, let get started !
The standard function to set a shader is :

GVertexShader(adress_of_function,sub_adress_projection)
.destroy r1,r2
you can of course get the adresse with the L operator.
sub_adresse_projection is kindy tricky. It is the adresse in your shader, where th projection calculation starts.

Once you've put this code, anywhere in your  program, GLib's functions will get override.

So let's see what you have to put inside this function.

Lbl Shader
GRestoreHL

Return

because some function need a correct hl you mostly want to restore it. As GLib do a goto before, hl get ecrased. But we have a variable to restore it  

a very basic shader (do nothing more than the GLib's GVertex command) would be then this:

Lbl Shader
GRestoreHL
GRotate()
Lbl SubShader   .the famous sub_adress
Goto GProject


it's first call the fuction who convert the r1,r2,r3   (and need r3 in hl) to the rotated coordinate in 3D space into OP1+6
GRotate(x,z,y)
.destroy r1-r3
.write to OP
You will then have the vertex rotated coordinate to these variable :

GVertexX
GVertexY
GVertexZ

Then it call the projection function to retrieve the x,y coordinate on screen

GProject()
.need the 3D coordinate Inside OP1+6 (°GVertex+6)

...and you can retrieve the 2D coordinate to these vars : (note that this function keep the 3D coordinates safe)

GScreenX
GScreenY

Based on this you can either :
-modify the vertex position before any rotation or after
-build your own rotation routine and projection (for example to have more precision)
-and everything you want...

Once you've done with the shader, you can disable it by doing :
GVertexShader(°GLIBFUNC)
yep it's the same function    pretty easy isn't it ?

let's create a custom shader then  
The goal is to make the camera moving up and down like in old fps. When the player is not moving, there should be no mouvement.
Let create a vars T who hold the current active/not active state. Each frame, compare the X,Y coordinate of the player with previous stored one. (A,B) - if it different, increase the Z var, use to hold an angle : the cosinus will give us the mouvemnt.

We now have this as shader :
Lbl TEST
GRestoreHL
GRotate()
Lbl TESTSUB
GProject()
!If T
signed{Z^256+°GCos}//32+GScreenY+2->GScreenY
End
Return

for each vertex, the point will be move on screen.

And then in the main loop, add this:

0->T
!f A-GCPosX   .GCPosX is the X coordinate of the camera
!f B-GCPosY
+1->T   .hl abuse...
End
End

GCPosX->A
GCPosY->B
If T
96->Z
Else
Z+8->Z   .increase the angle, so we can have the mouvement
End


and with variables initialisation :

0->A->B->T

So the whole code is :
(note that I change vertices to be more a world thing)

well, screen have different vertices but run the same shader :



One thing to remember :
DO NOT USE r4 to r6 !!. r1-r3 are fine though (but only after rotating)


IV And then come polygons.... [WARNING OUTDATED ]


the polygon system is in a separate library. So to use it, download the GPOLYGON file, and then put :

prgmGPOLYGON

a little warning : GPOLYGON is in alpha, bug may still there ! (and so ram clear too =\)

at the begin of your program, after the inclusion of the GCORE file. You can then acess all the new functions !

There is 3 extremely important function :
GDrawArray(adr_array,nb_of_poly)
.destroy r1 to r6
GPrimitive(start_adr)
.destroy r1 to r6
GSetColor(flag)
.destroy r1


I'll first explain GSetColor and GDrawArray, later GPrimitive

GSetColor is I guess pretty obvious. It is used to set the current drawing color.
Two flag are possible :
°GBLACK or °GWHITE (yes, it's constants)

every polygon drawn will have the color you set. Black is the default color.

GDrawArray can draw polygons according to a big bunch of datas. Data have a particular structure :

Data(Type_polygon,Color
Data(idVertex1,idVertex2,...
.all of this is one byte value

This function handle 3 type of polygon, with a special one :
-triangles       type is °GTRI
-quadrilater    type is °GQUAD
-sphere          type is °GSPHERE

the number of vertices you want to put is obviously the number of vertices in the polygon.

Why I say sphere is a special thing ? Cause data structure is different :

Data(type,color)
Data(centerVertexId,radius

where the centerVertexId is the id of the vertex representing the center of the sphere.

and then the GPrimitive function. I guess this is the most difficult.

the GPrimitive function take in input the pointer to a list of vertices' id, an you must set a particular variable before the call ; the GPolygon var.
Simply put the type ( the constant ) in it. The call will the look like this :

GSetColor(°GBLACK)
°GTRI->Gpolygon
GPrimitive(Data(0,1,2))

it wil draw, in black, a triangle between the first three vertex.

One last thing before the test code though, you remember the GVAdr and GVStr variables for the line clipping ? Well polygon work the same. Every function need correct value in these var.
Meaning that you have to rotate your vertex, store them, before call the Polygon function.    If a polygon you draw goes crazy, look if you don't forget this part.

And now, a little test program:


.TEST
prgmGCORE
prgmGPOLYGON

Data(40r,-40r,40r)→GDB1
Data(40r,40r,40r
Data(-40r,-40r,40r
Data(-40r,40r,40r
Data(40r,-40r,-40r
Data(40r,40r,-40r
Data(-40r,-40r,-40r
Data(-40r,40r,-40r

Data(0,1,2,3,4,5,6,7)->°LinkList
Data(0,2,2,4,4,6,6,0
Data(1,3,3,5,5,7,7,1

Buff(8*6)→GDB2


GNewCam(°GMODELVIEW)
GDB1→GVAdr
GDB2→GVStr

While 1

GDB1→r5
GDB2→r6

For(8)
GVertex({r5}r,{r5+2}r,{r5+4}r
copy(°GVertex,r6,6
r6+6→r6
r5+6→r5
End

For(M,0,11)    .there is 12 line to draw in a cube
GClipLine({M*2+°LinkList},{M*2+1+°LinkList}
End

°GQUAD->GPolygon
GPrimitive(Data(0,1,3,2))
.warning ! vertex must be clockwise or anticlockwise!

GGetkey(°GMODEL)

DispgraphClrdraw
EndIf getkey(15)


not much change ,heh ?
and the screen =)


still pretty strong, running at 20fps with a fully clipped model.

V VBO, extra functions, and pipeline informations...

We have already talked about VBO ... but how they work precisely ? follow the guide !

VBO are just a free place in memory, with an particular structure, and an id.
What is a VBO Id ? In fact, it is no more than the adress of the start of it.
Base on that, we can perfectly create our own VBO, without passing by the GGenVBO() command.You can perfectly, is L3 has been perfectly set up use this :
GSetCurVBO(L3)
.destroy r1

Bascially this command will change the current active VBO (read : used for rendering) to the one you specify.
So, what is this particular structure ? It is the following :

.1 bytes                              -- reserved field for GLib's, used for delete VBO (you don't really need this)
.2 bytes                              --number of vertices the VBO should handle at max
.2 bytes                              --raw vertices adress
.5*number of vertices bytes --the vertex on screen position, with their respective cliping code
.6*number of vertices bytes --the rotated vertices coordinates.

the screen coordiante is separate as follow :

.2 bytes X coordinate
.2 bytes Y coordinate
.1 byte clipping code

the cliping code can be computed, if the vertex position to classify is in the GVertexX to GVertexZ vars with :
GInFrustrum()/256
.destroy nothing
and return vertex status in hl :
-0 if the point is visible
-anything else if not


Now more about the GLib's pipeline. In fact, when you want to draw a line, or any polygon, the classical pipeline will be :


-green : vertex operation
-red : shader
-blue : geometric operation
-white : outside GLib data operation.

Indeed, this is a simplified one - especially into the graphics commands. The last stage can be decomposed in many other one, but the GCORE lib doesn't really touch these. It's more the goal of the GPOLY lib (wich is for the moment outdated).


Other tutorials are coming, I will then organize this post with them.

Ui, a tutorial for this, that helps understand how it works a lot

Sounds interesting. Definitely gonna try it out.

If i can critique one thing :p

I like this tutorial but i thinks that the name of your routine is a lot of big example : GNewCam(pointer to camera) can be Camera(pointer to camera) this is more clear when we read the code

Oh, I just assumed that it was wrong because it was different in the tuturial as in the full code. I don't really know many of the axe optimisation tricks.

It would definitively be nice if you could expand the tutorial further so that it also teaches how to make programs where the dots are connected with lines or maybe even textures.

Also maybe uploading a copy of the tutorial at http://www.omnimaga.org/index.php?action=articles;cat=12 when it's completed.

Tutorial as been updated 

new tuto on Shader !