GLSCENE User Tutorials - Build a basic scene

From here on we assume the GLScene library has been installed properly. We are ready to take our first steps into the 3D openGL universe. In GLScene the universe or 3D world is called a scene. Hence the name. We are going to create our first application that will contain a 3D cube. We will learn how to start a basic GLScene application and how to control the layout by manipulating the design time properties.

Start a new application in Delphi Set the form width to 640 and the height to 480

- Go to the GLScene tab on the VCL palette

- Place a TGLScene

and a TGLSceneViewer

viewer on the form

The TGLSceneViewer is the window which will give us a view into the 3D scene we are about to build. The TGLSene is the master of the scene. Everything that happens is managed through the TGLScene control. Lets introduce you to the most important dialog in GLScene. The scene editor.

Right click on the TGLScene editor

icon on the form and select Show scene

As a result the scene editor dialog will appear.

The world managed by TGLScene is still a blank canvas. You can add objects such as shapes, cameras and lights to build your world in this editor.

Lets start by adding a 3D cube to the scene.

Right click on

Scene Objects and select a Cube from Basic geometry

You can see there are a lot of objects you can choose from. Leave those for what they are for now. We will visit other objects later in the tutorial. The popup menu will collapse once you click on the the scene. Cube object. The cube is now added to

Lets close the scene editor and check out wat we see.

???? Nothing! Why cant you see the cube? Well that would be correct. There is a whole bunch of things that need to be considered before you will see anything.

In the previous topic you build a GLScene application but so far you could not see any results. Why cant you see the cube? Well in order for you to see anything at all you will need to create a way to view the scene. This is done using a camera. We are now going to add a camera to the scene.

Need to know
The scene editor doesnt always know where you click on. A work around is to select any other node in the editor and then select the node you want. Only then will the object inspector (F10) and the context popup menu be correct.

Left click on Left click on

"Scene objects" to make that option active "Cameras" to make that option active

This weird toggle action will sort out the Scene editor if it gets confused. Use this trick whenever the object inspector or context menu fails to show the correct information.

Open the scene editor again. Right click on the TGLScene form and select Show scene editor Right click on Cameras and select Add camera

icon on the

You now have a camera but dont bother to go and check out your creation on the form. There is still nothing there!

Need to know
Every new object that is created is always placed in the center of the scene by default.

So you can see that the camera occupies the same space as the cube. Besides the camera points at some default direction and chances are that it is not pointing to the cube anyway. Well that is easy to fix. We are going to tell the camera to look at the cube

Select

GLCamera1 and press F10 to bring up the object inspector.

In the object inspector you will see the camera properties.

Set the TargetObject to GLCube1

From now on the camera will always point at GLCube no matter where the Cube or camera is located. Still the GLSceneViewer wont show anything. The main reason for this is that the viewer has not yet been told for which camera it should display a view. In GLScene you can have multiple cameras and you can switch your view from one camera to another.

Close the Scene editor Select the TGLSceneviewer control Press F10 to bring up the object inspector

One of the properties of a tGLSceneViewer is the Camera property. This property defines wich camera should be used to render the 3D view for the viewer.

Set the Camera property to GLCamera1

Still nothing to see. Lets summarize what we have done and see if we can identify what we have missed.

We created a cube and a camera. We told the camera to look at the cube. We told the viewer to use camera1. However, we never told the camera and cube where to go!

The camera is located in exactly the same spot as the cube so basically were too close to see anything at all. For now lets just get this thing working. After that we need to spend some time to talk about 3D coordinates.

Right click on the TGLScene

icon on the form and select Show scene

editor Select GLCamera1 and press F10 to bring up the object inspector. Set the position coordinates to X=1, Y=1 and Z=1

Finally, something appears on the screen. It looks pretty bad but at least its something

right?

What you see is the silhouette of a 3D cube as seen from an angle. It is all black because There are no lights! Every scene needs lights. Without lights you cant see anything. So lets add a light.

Right click on the TGLScene editor Right click on

icon on the form and select Show scene

Scene Objects and select a Lightsource

Nothing changed. The new light is added to the center of the scene and in our case the light would end up in the inside of the cube. We need to move the light up to get it out of the cube.

Select the new light in the scene editor and press F10 to bring up the object inspector. Change the position of the light as shown below.

And finally the cube is shown in all its glory.

Congratulations you have mastered the very basics of GLScene. We have created an application containing a TGLScene and a TGLSceneViewer We have added a cube, a

camera and a light. We told the viewer to use our new camera. We made the camera look at the cube and placed the camera away from the cube so it can look at it. We added a light and placed it above the cube and presto we are done! So the minimum requirements in order for you to see anything in GLScene are:

TGLScene component (The scene master object) TGLSceneViewer (To see stuff) TGLCamera (were to see stuff from) TGLLight (So we can see stuff) TGLCube (Stuff to see)

Obviously these objects need to be configured in such a way that the camera can actually see the cube and the light can shine on the outside of the cube. Although we have achieved to display a 3D object in Delphi, we need to be able to

manipulate the object in 3D space. Gain control so to speak. Save this project and name it "glscenebase.dpr" or something. You will find that it will come in handy every time you want to try something. Also you will need this project for the next tutorial. The Control Objects tutorial will teach you how to control objects in space.

Control Objects
So we know how to move thing around in 3D space but we still need to learn how to manage their orientation. This topic will explain the do's and don't of Object orientation. Object orientation is basically the art of rotating an object around it's X, Y and Z axis. So far we have explained every step in detail. Before we continue we will list knowledge we assume from now on. We assume you know how to: * Open the scene editor * Add objects to the scene * How to select objects * How to access the objects properties.

Now we have a 3D cube in a viewer we can start messing around with the cubes position. The coordinate system in GLScene uses three axis that are perpendicular to each other. The manage placement in X, Y and Z direction. Lets illustrate this by turning on the Show Axis property of the cube. * Select the cube in the object inspector and set the Show axis property to True

A 3 colored axis system is now shown.

The three axis you see here are the X, Y and Z axis. X axis is Red Y axis is Green Z axis is Blue The intersection of these three axis is coordinate X=0.0, Y=0.0 and Z=0.0 which is where the cube is currently placed. We call this system of coordinates a coordinate system. Now here is where things may become confusing: Every object has its own coordinate system! For now just accept this as a fact. Later you will find out the incredible power that can be gained from having this feature. By default objects created in GLScene have a size of 1 unit. Therefore the cube is 1 unit wide, 1 unit height and 1 unit deep. You may wonder how large a unit is but in our 3D world a unit is whatever you want it to be as long as you are consistent. A unit can be an inch, a furlong, a centimeter or the length of your little pinky.

Lets move the cube along the x axis by changing the position.x property of the cube from 0 to 1. This should move the cube along the red X axis by exactly the width of the cube.

Set the Position.X property of GLCube1 to 1

The result wont be what you expected:

What happened? Well the cube moved along the X axis as intended but the camera is programmed to keep looking at GLCube1. So the camera turned to follow GLCube1 and the above image is the result. We need to give the camera a fixed reference that does not move. A quick and easy way is to use another object that stays in place while the cube moves around. Introducing the Dummy cube. This cube can be seen during design-time as a wireframe cube but is not rendered during run-time. The cube however is still very much part of the object structure. Lets try this

Open the scene editor and add a dummycube Select the camera and set its Target property to GLdummyCube1

Have a look at the form now.

The camera orientation has gone back to what it was before we changed the GLCube1 position.X coordinate. The white dashed wireframe shows the position of the GLDummyCube1. That is where the GLCube1 used to be. Now play with the coordinates of GLCube1 a little. Change Position.X Y and Z and see if you can place the cube in the lower left corner of the viewer. Coordinates in GLScene are of type Single. You can therefore enter fractions such as 0.43 and so on. Try both positive values and negative values. Need to know: The default values for a camera define a NearPlaneBias with a value of 1. When object come close to the camera they get clipped by this plane. This is the reason that the Cube in the above picture has a corner missing. You can make this clipping go away by decreasing the NearPlaneBias from 1 to say 0.1

Once you feel familiar with the position coordinates you can go-ahead and move the cube to its final position:

Set the GLCube1.position.x = 0 Set the GLCube1.position.y = -0.5 Set the GLCube1.position.z = 0

We are now going to do some more work with coordinates. This time we will use a TGLLines object. TGLLines can draw a polyline in 3D space. The final line drawn can be made up of straight line segments or a spline can be drawn through its points.

Open the Scene editor and add a Lines object.

The form will look like this:

As you can see the GLCube1 has moved down half a unit but there is no line anywhere in sight. This makes sense because we have yet to define the points that make up the line. We are going to create the outline of a simple house shape. The points of a TGLLines object are called nodes. Lets add a few nodes and keep an eye on the form to see where they end up. To make identification of the node points easier we will set a few properties first.

Select the GLLines1 object in the scene editor and press F10 to get the object inspector. Set the Linecolor to clrAquamarine Set LineWidth to 4 Set NodesAspect to lnaCube Set NodeSize to 0.1

We have now told GLLines1 to draw its lines in aqua marine color 4 pixels wide and mark every node in the polyline with a cube with a size of 0.1 units wide, high and deep. Lets get to work and add some nodes.

In the above object inspector click on Nodes to bring up the nodes collection dialog

Click on the familiar Add button to add a node. Each node can be given a color and an X,Y,Z coordinate. Lets start with the top of the roof of our house shape:

Enter 0.5 for the Z coordinate

Add nodes until you have the following collection:

Try not to look and figure out the coordinates for yourself to obtain this shape:

Need to know: Note how all Y values have been left to 0. In GLScene the Y axis is going up. The above GLLines1 object is flat with all its Y coordinates set to zero.

Can you create a set of nodes that allows the house to stand upright? I bet you are bored

with coordinates. Same here, lets see if we achieve this upright house in a different way. There are two things that define an object in space. Position and Orientation. We know about position now. The next tutorial will teach you how to manage an objects orientation through rotation. Make sure you save the work you have done so far because the next tutorial is based on it.

Control Objects
So we know how to move thing around in 3D space but we still need to learn how to manage their orientation. This topic will explain the do's and don't of Object orientation. Object orientation is basically the art of rotating an object around it's X, Y and Z axis. So far we have explained every step in detail. Before we continue we will list knowledge we assume from now on. We assume you know how to: * Open the scene editor * Add objects to the scene * How to select objects * How to access the objects properties.

Now we have a 3D cube in a viewer we can start messing around with the cubes position. The coordinate system in GLScene uses three axis that are perpendicular to each other. The manage placement in X, Y and Z direction. Lets illustrate this by turning on the Show Axis property of the cube. * Select the cube in the object inspector and set the Show axis property to True

A 3 colored axis system is now shown.

The three axis you see here are the X, Y and Z axis. X axis is Red Y axis is Green Z axis is Blue The intersection of these three axis is coordinate X=0.0, Y=0.0 and Z=0.0 which is where the cube is currently placed. We call this system of coordinates a coordinate system. Now here is where things may become confusing: Every object has its own coordinate system! For now just accept this as a fact. Later you will find out the incredible power that can be gained from having this feature. By default objects created in GLScene have a size of 1 unit. Therefore the cube is 1 unit wide, 1 unit height and 1 unit deep. You may wonder how large a unit is but in our 3D world a unit is whatever you want it to be as long as you are consistent. A unit can be an inch, a furlong, a centimeter or the length of your little pinky.

Lets move the cube along the x axis by changing the position.x property of the cube from 0 to 1. This should move the cube along the red X axis by exactly the width of the cube.

Set the Position.X property of GLCube1 to 1

The result wont be what you expected:

What happened? Well the cube moved along the X axis as intended but the camera is programmed to keep looking at GLCube1. So the camera turned to follow GLCube1 and the above image is the result. We need to give the camera a fixed reference that does not move. A quick and easy way is to use another object that stays in place while the cube moves around. Introducing the Dummy cube. This cube can be seen during design-time as a wireframe cube but is not rendered during run-time. The cube however is still very much part of the object structure. Lets try this

Open the scene editor and add a dummycube Select the camera and set its Target property to GLdummyCube1

Have a look at the form now.

The camera orientation has gone back to what it was before we changed the GLCube1 position.X coordinate. The white dashed wireframe shows the position of the GLDummyCube1. That is where the GLCube1 used to be. Now play with the coordinates of GLCube1 a little. Change Position.X Y and Z and see if you can place the cube in the lower left corner of the viewer. Coordinates in GLScene are of type Single. You can therefore enter fractions such as 0.43 and so on. Try both positive values and negative values. Need to know: The default values for a camera define a NearPlaneBias with a value of 1. When object come close to the camera they get clipped by this plane. This is the reason that the Cube in the above picture has a corner missing. You can make this clipping go away by decreasing the NearPlaneBias from 1 to say 0.1

Once you feel familiar with the position coordinates you can go-ahead and move the cube to its final position:

Set the GLCube1.position.x = 0 Set the GLCube1.position.y = -0.5 Set the GLCube1.position.z = 0

We are now going to do some more work with coordinates. This time we will use a TGLLines object. TGLLines can draw a polyline in 3D space. The final line drawn can be made up of straight line segments or a spline can be drawn through its points.

Open the Scene editor and add a Lines object.

The form will look like this:

As you can see the GLCube1 has moved down half a unit but there is no line anywhere in sight. This makes sense because we have yet to define the points that make up the line. We are going to create the outline of a simple house shape. The points of a TGLLines object are called nodes. Lets add a few nodes and keep an eye on the form to see where they end up. To make identification of the node points easier we will set a few properties first.

Select the GLLines1 object in the scene editor and press F10 to get the object inspector. Set the Linecolor to clrAquamarine Set LineWidth to 4 Set NodesAspect to lnaCube Set NodeSize to 0.1

We have now told GLLines1 to draw its lines in aqua marine color 4 pixels wide and mark every node in the polyline with a cube with a size of 0.1 units wide, high and deep. Lets get to work and add some nodes.

In the above object inspector click on Nodes to bring up the nodes collection dialog

Click on the familiar Add button to add a node. Each node can be given a color and an X,Y,Z coordinate. Lets start with the top of the roof of our house shape:

Enter 0.5 for the Z coordinate

Add nodes until you have the following collection:

Try not to look and figure out the coordinates for yourself to obtain this shape:

Need to know: Note how all Y values have been left to 0. In GLScene the Y axis is going up. The above GLLines1 object is flat with all its Y coordinates set to zero.

Can you create a set of nodes that allows the house to stand upright? I bet you are bored

with coordinates. Same here, lets see if we achieve this upright house in a different way. There are two things that define an object in space. Position and Orientation. We know about position now. The next tutorial will teach you how to manage an objects orientation through rotation. Make sure you save the work you have done so far because the next tutorial is based on it.