Click here to Skip to main content
15,867,320 members
Articles / Multimedia / OpenGL

SimpleScene: 3d scene manager in C# and OpenTK

Rate me:
Please Sign up or sign in to vote.
4.94/5 (40 votes)
27 Dec 2014Apache13 min read 134.8K   64   37
A simple open-source scene manager, and WavefrontOBJ file loader in C# and OpenGL (OpenTK). Runs on MacOS, Windows, and Linux.

Introduction

This article describes SimpleScene, a simple 3d scene manager, written in C# and the OpenTK managed wrapper around OpenGL. The code (and binaries!) run unmodified on Mac, Windows, and Linux. The code also includes a WavefrontOBJ file reader in C#. 

Image 1

 

Background

When writing a game, it is often advantageous to start with a 3d engine, such as Unity, Torque, Unreal Engine, or an open-source option such as Ogre or Axiom. However, if your goal is to get your hands dirty and learn about OpenGL, GLSL, and 3d engine concepts, the sheer size and complexity of those projects can be overwhelming. 

SimpleScene is a small 3d scene manager and 3d example intended to fill this need. I've attempted to favor directness in the code over flexible abstractions, as this makes it easier to follow, learn from, and modify. The code is offered into the public domain, without any license restrictions. You can check it out or download it from the SimpleScene github.

The WavefrontOBJLoader example program is based on the transitional GLSL 120, because it has very wide device compatibility. This is the first GLSL which supports geometry shaders, which were used to implement single-pass wireframes-- a shader-based method of adding object wireframes which doesn't have the perfomance and visual artifacts of re-drawing GL-Lines over the object.

What is a Scene Manager?

In short, a scene-manager takes care of managing and drawing your 3d scene of objects, so you can think at the abstraction of moving 3d objects around, isntead of how to transform and paint them into a camera and viewport. 

3d APIs such as OpenGL, Direct3d, and WebGL are called immediate-mode rendering APIs. They allow you to take a clear buffer of pixels and start painting 3d shapes, or rasterizing, into that buffer. The set of shapes drawn into the buffer is commonly referred to as a scene. Therefore, a scene-manager takes over the work of transforming a set of objects, their positions, orientations, animation states, rendering states, and any other relevant information -- into a set of immediate mode calls. 

Is a Scene Manager a Game Engine?

Not exactly, and the line between them is definetly fuzzy.

A game-engine contains a scene-manager, but it typically also contains lots of other code assuming that the program will act in a particular way. The most common game-engine assumptions are things like (a) assuming only a single operating system window, (b) assuming a continuous-repaint update-redraw, where the full scene is updated every frame, and (c) object meshes are not arbitrarily edited. Making assumptions like this makes it simpler to integrate physics, collision detection, and even certain types of object networking to work right out of the box. However, these assumptions may also be deeply ingrained in the code-base, making it impractical to use the game-engine for non-game applications. 

A scene-manager, on the other hand, is more general purpose. SimpleScene does not set policies about building a particular type of application. Following the examples above, SimpleScene (a) does not create windows, so you can create and control them as you like, (b) does not have a render loop, allowing you to control when and how to repaint portions of your window, and (c) allows you to plug in whatever type of mesh-handers you like, including mesh-representations which are editable. On the other hand, it does not come with physics or collision detection either. 

For example, SimpleScene currently includes functionality for:

  • rendering 3d meshes through opengl, including support for loading WavefrontOBJ files
    • multi-texture rendering (diffuse, specular, and ambient/glow maps)
    • object wireframes, via GLSL single-pass or brute-force GL line over-draw
    • CPU frustrum culling
    • Dynamic Bounding-Volume-Hiearchy, for space-partitioning
  • 3d object "picking" through CPU mouse-ray intersection tests (bounding sphere and precise-mesh)
  • cross-platform 2d vector and font drawing via a GDI-like wrapper around agg-sharp

However, it does *not* include features typically found in modern game engines:

  • collision detection or physics
  • dynamic lighting
  • threaded simulation, networking, threaded rendering (yet!)

How do I use a scene manager?

At the highest level, you must create a viewport window, decide how many scenes you would like to render into that viewport, and setup the matrix transformations required to project each scene into your viewport. 

SimpleScene includes an example WavefrontOBJLoader program, which loads a sample skybox, OBJ 3d model "spaceship", and draws a GL-Point based starfield environment. We're not going to review every element of using OpenGL or OpenTK here, but instead provide a glance over some of the main elements. You can load, compile, and run this project using either Visual Studio or Xamarin / MonoDevelop. 

The rendering for WavefrontOBJLoader is split into three different scenes. A scene is a set of objects which are rendered together, into the same camera and screen viewport projection. These are declared in Main.cs, and setup in Main_setupScene.cs:

C++
        SSScene scene;
        SSScene hudScene;
        SSScene environmentScene;

Our environmentScene includes our skybox and starfield, and is rendered in an "infinite projection". It's projected into the viewport using the camera rotation, but not it's position. It also ignores z-testing and is drawn first. This gives it the appearance of being infinitely far away. 

Our hudScene includes the FPS display and wireframe toggle instructions. It's a special scene which is rendered without a 3d perspective projection, making it easy to put 2d UI elements onto the top of the scene rendering. This type of layer is nicknamed HUD after the heads-up-display on a pilot's visor.

Our scene includes the 3d elements being drawn, which in this case is just two copies of the main 3d model we loaded. 

Add Objects to a Scene

In order for there to be something interesting to render, we need to add objects to the scene. you can see this happening in Main_setupScene.cs. Here is how we add the main "spaceship" model, loaded from our OBJ/MTL file and textures.

C#
    // add drone
    SSObject droneObj = new SSObjectMesh (
            new SSMesh_wfOBJ (
                  SSAssetManager.mgr.getContext ("./drone2/"),   // directory context
                  "drone2.obj",                                  // model filename
                  true, shaderPgm));                             // shader program to use
    scene.addObject (this.activeModel = droneObj);               // add it to the scene

    // setup some rendering and lighting paramaters
    droneObj.renderState.lighted = true;
    droneObj.ambientMatColor = new Color4(0.2f,0.2f,0.2f,0.2f);
    droneObj.diffuseMatColor = new Color4(0.3f,0.3f,0.3f,0.3f);
    droneObj.specularMatColor = new Color4(0.3f,0.3f,0.3f,0.3f);
    droneObj.shininessMatColor = 10.0f;

    droneObj.MouseDeltaOrient(-40.0f,0.0f);                      // turn it slightly
    droneObj.Pos = new OpenTK.Vector3(-5,0,0);                   // move it off the origin

The 2d HUD objects are added in a similar way, only we leave the z-coordinate set to zero.

C#
// HUD text....
fpsDisplay = new SSObjectGDISurface_Text ();
fpsDisplay.Label = "FPS: ...";
hudScene.addObject (fpsDisplay);
fpsDisplay.Pos = new Vector3 (10f, 10f, 0f);
fpsDisplay.Scale = new Vector3 (1.0f);

Render the Scene

You can see these three scenes being setup and rendered inside Main_renderScene.cs and the OpenTK game-window callback OnRenderFrame. First we clear the render buffer:

C#
     // clear the render buffer....
     GL.Enable(EnableCap.DepthTest);
     GL.DepthMask (true);
     GL.ClearColor(0.0f, 0.0f, 0.0f, 0.0f); // black
     // GL.ClearColor (System.Drawing.Color.White);
     GL.Clear(ClearBufferMask.ColorBufferBit | ClearBufferMask.DepthBufferBit);

Then we setup a an "infinite project" matrix to render the environment Scene, which includes the skybox. Because we're rendering the skybox first, we disable depth testing entirely. A more modern technique is to render the skybox after rendering all opaque objects, and forced to "infinite depth" with depth testing on. This avoids writing skybox pixels which are fully occluded by solid geometry. However, I stuck with the simplicity of rendering it first.

C#
// render the "environment" scene
//
// todo: should move this after the scene render, with a proper depth
//  test, because it's more efficient when it doesn't have to write every pixel
{
  GL.Disable(EnableCap.DepthTest);
  GL.Enable(EnableCap.CullFace);
  GL.CullFace (CullFaceMode.Front);
  GL.Disable(EnableCap.DepthClamp);

  // setup infinite projection for cubemap
  Matrix4 projMatrix = Matrix4.CreatePerspectiveFieldOfView (fovy, aspect, 0.1f, 2.0f);
  environmentScene.setProjectionMatrix (projMatrix);
  // environmentScene.setProjectionMatrix(projection);

  // create a matrix of just the camera rotation only (it needs to stay at the origin)
  environmentScene.setInvCameraViewMatrix (
       Matrix4.CreateFromQuaternion (
            scene.activeCamera.worldMat.ExtractRotation ()
       ).Inverted ());

  environmentScene.Render ();
}

Then we setup the perspective projection and render the main-scene's 3d objects. 

C#
// rendering the "main" 3d scene....
{
   GL.Enable (EnableCap.CullFace);
   GL.CullFace (CullFaceMode.Back);
   GL.Enable(EnableCap.DepthTest);
   GL.Enable(EnableCap.DepthClamp);

   GL.DepthMask (true);

   // setup the inverse matrix of the active camera...
   scene.setInvCameraViewMatrix (scene.activeCamera.worldMat.Inverted ());

   // setup the view projection. technically only need to do this on window resize..
   Matrix4 projection = Matrix4.CreatePerspectiveFieldOfView (fovy, aspect, 1.0f, 500.0f);
   scene.setProjectionMatrix (projection);

   // render 3d content...
   scene.SetupLights ();
   scene.Render ();
 }

Finally, we setup an orthographic matrix, and render the HUD scene elements.

C#
      //  render HUD scene

      GL.Disable (EnableCap.DepthTest);
      GL.Disable (EnableCap.CullFace);
      GL.DepthMask (false);

      hudScene.setProjectionMatrix(Matrix4.Identity);
      hudScene.setInvCameraViewMatrix(
           Matrix4.CreateOrthographicOffCenter(0,ClientRectangle.Width,ClientRectangle.Height,0,-1,1));

      hudScene.Render ();

After the scene is rendering, you'll probably want some code enabling the user to interact with scene elements. In our simple example, the only interaction we have is with the camera. The mouse wheel zooms it in and out, and dragging orbits it around our model object. We also setup the key 'w' to toggle between three different wireframe display modes. You can see the handlers for this in Main_setupInput.cs. 

How does a Scene Manager draw the scene?

Under the covers, the scene manager keeps track of all the objects in the scene, their positions, and their transformation matricies. Whenever it's asked to render the scene, it walks the scene, updating the projection matrix before rendering the object out to the immediate-mode API, in this case OpenTK / OpenGL. 

A very simple example of drawing a mesh can be found in SSObjectCube.cs. This class renders a unit-sized cube using the legacy OpenGL API.  It doesn't have to manage matricies, because the scene-manager has already handled that for us in SSScene and SSObject. This makes the Render code easy to follow, as it just renders itself using OpenGL as if it is centered at the origin.

C#
    public override void Render(ref SSRenderConfig renderConfig) {
         base.Render (ref renderConfig);

         // define the corners of a cube
         var p0 = new Vector3 (-1, -1,  1);  
         var p1 = new Vector3 ( 1, -1,  1);
         var p2 = new Vector3 ( 1,  1,  1);  
         var p3 = new Vector3 (-1,  1,  1);
         var p4 = new Vector3 (-1, -1, -1);
         var p5 = new Vector3 ( 1, -1, -1);
         var p6 = new Vector3 ( 1,  1, -1);
         var p7 = new Vector3 (-1,  1, -1);

         GL.Begin(BeginMode.Triangles);
         GL.Color3(0.5f, 0.5f, 0.5f);
            
         // draw the faces of the cube
         drawQuadFace(p0, p1, p2, p3);            
         drawQuadFace(p7, p6, p5, p4);
         drawQuadFace(p1, p0, p4, p5);
         drawQuadFace(p2, p1, p5, p6);
         drawQuadFace(p3, p2, p6, p7);
         drawQuadFace(p0, p3, p7, p4);

         GL.End();
     }

For clarity, our implementation of drawQuadFace uses the legacy OpenGL drawing-calls, which involve calling a function per paramater. While this is easy to read when trying to understand 3d, calling a GL function for every vertex has gone the way of the dodo-bird. Modern OpenGL 2+, OpenGLES, and Direct3D have eliminated this calling-interface in favor of much faster vertex-buffers, which we'll talk about later. This is because calling a function per vertex is incredibly slow, and from a managed-language like C# it's positively lethargic. Every one of those GL.Vertex3() calls is hopping through a managed-to-native thunk.

Here you can see the code it uses to draw each quad-face of the cube:

C#
private void drawQuadFace(Vector3 p0, Vector3 p1, Vector3 p2, Vector3 p3) {

    GL.Normal3(Vector3.Cross(p1-p0,p2-p0).Normalized());
    GL.Vertex3(p0);
    GL.Vertex3(p1);
    GL.Vertex3(p2);

    GL.Normal3(Vector3.Cross(p2-p0,p3-p0).Normalized());
    GL.Vertex3(p0);
    GL.Vertex3(p2);
    GL.Vertex3(p3);
}

To under more modern vertex-buffers and index-buffers, as well as texturing, we'll need to look at SSMesh_wfOBJ.cs. This class understands how to take the data-model produced by the WavefrontOBJLoader class, and format it for rendering through OpenGL. Because Wavefront OBJ doesn't support animations, the format is rather simple. It's a list of geometry subsets, each mapped to a material definition. That material-definition may include static shading colors and up-to four textures (diffuse, specular, ambient, and bump). 

When dealing with static (non-animated) 3d meshes, quite a bit of the work is just shuffling buffers of bits around, converting from one format to another. The wavefront file loader moves 3d data from the ascii file-format into an intermediate in-memory representation. The SSMesh_wfOBJ.cs then loads and passes that data to OpenGL, by setting up data-structures for the information, passing them as vertex-and-index buffers, and sending textures to the videocard. When rendering, SSMesh_wfOBJ then just points the GPU at these datasets and pushes the "do your thing button", and voila, 3d shapes come out.

Okay, it's not quite as simple as that, but it's close. The one additional piece of magic we have not talked about is the shaders, written in a language called GLSL (the OpenGL Shading Language). Direct3d has it's own equivilant HLSL. For a while, Nvidia had their own special shading language called Cg which attempted to provide one language which would convert into GLSL and HLSL, but it's been depreciated. Now we all write GLSL for cross-platform OpenGL, and HLSL for Windows Direct3D.

What is a shader?

Long long ago, 3d rasterization hardware included a fixed-function set of capabilities. At first hardware could render shaded triangles only, with no image texture. Then eventually it was possible to add a single-texture to the triangles. Then someone had the idea to layer and combine multiple textures onto the same triangle. Each generation of the hardware was fixed-function, in that it could do only what it was designed to do, no more, and no less.

As 3d hardware became more and more popular, the software folks started tricking the hardware into doing things the fixed-functions were not intended to do, by creating odd texture-inputs and using the fixed blend modes in strange ways. Eventually, everyone realized these graphics chips would be much more useful and flexible if they had software of their own -- and thus began the path to the modern day general-purpose GPU. 

Your GPU is much like your CPU, with one special difference. Wheras your CPU is designed to run one copy of a really really large software program. Your GPU is designed to run lots of simultaneous copies of a really really small software program. Those really small programs are called shaders. When we use them for 3d rendering, they handle the many small tasks in 3d rendering which must be repeated millions and millions of times per frame..

Vertex operations happen once per vertex. Geometry operations happen once per geometric primitive (i.e. triangle), and pixel operations happen once per pixel (only we call them fragments or texels, not pixels). This yields the three types of shaders: Vertex shaders, Geometry shaders, and Fragment shaders. 

Just like our SSObjectCube class is written as if it's the only cube in existance, a shader too is written to handle only a single operation. It's invoked once for each occurance of that type of operation, often simultaneously across the GPU hardware's highly parallel shader units. This means shader programming is a bit different than regular programming. We can't talk to any of the other occurances of shaders which are running, because we have no idea if or when they might run. A shader just deals with the inputs of it's task at hand, and outputs what is required.

There are books and websites dedicated to explaining the details of shaders and shader programming. At this point we're going to jump right into SimpleScene shaders, and how our example project's shader works.

Our Shaders and Single-Pass-Wireframes

Our shaders are setup in Main_setupShaders.cs. The asset manager finds them in Assets/shaders. Each type of shader is in its own file. 

I admit that my intent in keeping SimpleScene as simple and direct as possible has failed a bit in the shaders. Currently I have three different shading techniques mixed into one pile of shaders. (a) a basic per-pixel glow+diffuse+specular shader, (b) the single-pass wifeframe calculations, and (c) a not-yet-working bump-mapping shader. In the future I plan to clean this mess up, fix the bump mapping, and separate these into separate shaders so it's easier to understand. However, I didn't want perfect to be the enemy of good, and so you get to see my work-in-progress shader code.

The first thing to note about our shaders is that they are using GLSL 120. This is a "transitional" form of GLSL, in that it has one-foot in the world of legacy fixed-function pipelines, and one foot in the world of modern GPU programming. I used this for two specific reasons. First, it has the widest hardware compatibility - specificaly it is the most compatible GLSL with geometry shaders necessary for single-pass wireframes. Second, because it works easily with both legacy OpenGL function-per-paramater calls, and vertex-buffers, it allows the rest of SimpleScene to intermix these two modes easily while still using the same shader code. Once we move to modern GLSL, the entire fixed-function pipeline is gone, the functional interface no longer works, and all data is supplied to the card via generic buffers. This is better, more general purpose, and more efficient, but not necessarily better from an educational standpoint -- one of the major goals of SimpleScene.

In traditional wireframe rendering, the object is drawn once normally, then again as a set of wireframe lines. This has several issues, first, it's slow to draw the object twice. Second, the lines "z-fight" with the original model, and are sometimes not visible. Workarounds can try to make them more visible in more cases, but no workaround is perfect. A better solution, is single-pass wireframes in GLSL. Rather than drawing separate wireframe lines, we simply calculate the pixels of a triangle which lie on the edge, and paint those a different color while rendering the triangle. This allows us not only to avoid the two problems above, but it also allows us to adjust the color of the wireframe based on the pixels it's painting over (dark on light and light on dark). Here are screenshots of the results:

 

Image 2Image 3

 

You can learn more about how OpenGL shading works, and about these shaders, by reading the code, the references below, and just poking around and experimenting with on your own.  If you have questions about specific parts of the code, or how to achieve an effect yourself, post in the comments and I'll do my best to answer.

Followup Questions?

Having trouble understanding part of the code? Want advice about how to add a specific feature? Post a topic below and I'll do my best to answer.

References

History

  • 2014-07: added GDIviaAGG for cross-platform 2d vector graphics
  • 2014-07: added ray-intersection based 3d picking (bounding sphere and precise-mesh)
  • 2014-07: first release of code and article

 

License

This article, along with any associated source code and files, is licensed under The Apache License, Version 2.0


Written By
United States United States
David Jeske is an Entrepreneur and Computer Programmer, currently living in San Francisco, California.

He earned his B.S. Computer Engineering at University of Illnois at Champaign/Urbana (UIUC), and has worked at several Silicon Valley companies, including Google, Yahoo, eGroups.com, 3dfx, and Akklaim Entertainment. He has managed and architected extremely high-traffic websites, including Yahoo Groups and orkut.com, and has experience in a broad spectrum of technology areas including scalability, databases, drivers, system software, and 3d graphics.

You can contact him at davidj -a-t- gmail (dot) com for personal messages about this article.

Comments and Discussions

 
Questionhow to host the gamewindow into a WPF control such as a panel? Pin
GPGPU24-Mar-19 4:13
GPGPU24-Mar-19 4:13 
AnswerRe: how to host the gamewindow into a WPF control such as a panel? Pin
Member 1450396118-Jun-19 16:17
Member 1450396118-Jun-19 16:17 
QuestionCan't change texture colors Pin
E3pO22-Jun-15 19:15
E3pO22-Jun-15 19:15 
Hey, awesome tool.

I'm having issues changing the colors of objects, i figured all i would need to do is change this...

C#
droneObj.AmbientMatColor = new Color4(0.6f, 0.7f, 0.7f, 0.7f);
            droneObj.DiffuseMatColor = new Color4(objColorR, objColorG, objColorB, objColorA);
            droneObj.SpecularMatColor = new Color4(objColorR, objColorG, objColorB, objColorA);
            droneObj.EmissionMatColor = new Color4(objColorR, objColorG, objColorB, objColorA);


But no matter what i do, it never actually changes. Any ideas?
GeneralMy vote of 5 Pin
Shmuel Zang26-Apr-15 7:09
Shmuel Zang26-Apr-15 7:09 
GeneralMy vote of 5 Pin
User 1106097918-Dec-14 8:12
User 1106097918-Dec-14 8:12 
QuestionWireframe colors Pin
gameengineer15-Dec-14 9:54
gameengineer15-Dec-14 9:54 
AnswerRe: Wireframe colors Pin
David Jeske15-Dec-14 20:20
David Jeske15-Dec-14 20:20 
GeneralRe: Wireframe colors Pin
gameengineer16-Dec-14 9:36
gameengineer16-Dec-14 9:36 
GeneralRe: Wireframe colors Pin
David Jeske16-Dec-14 10:39
David Jeske16-Dec-14 10:39 
GeneralRe: Wireframe colors Pin
gameengineer16-Dec-14 12:16
gameengineer16-Dec-14 12:16 
GeneralRe: Wireframe colors Pin
David Jeske16-Dec-14 15:34
David Jeske16-Dec-14 15:34 
QuestionbindGLAttributes Pin
LinJiaRui17-Oct-14 16:43
LinJiaRui17-Oct-14 16:43 
AnswerRe: bindGLAttributes Pin
David Jeske17-Oct-14 17:02
David Jeske17-Oct-14 17:02 
QuestionVery good article! Pin
Volynsky Alex7-Oct-14 11:58
professionalVolynsky Alex7-Oct-14 11:58 
Questionnice article Pin
kasix21-Sep-14 7:21
kasix21-Sep-14 7:21 
AnswerRe: nice article Pin
David Jeske21-Sep-14 13:48
David Jeske21-Sep-14 13:48 
GeneralMy vote of 5 Pin
Paulo Zemek20-Aug-14 9:39
mvaPaulo Zemek20-Aug-14 9:39 
GeneralMy vote of 5 Pin
Ștefan-Mihai MOGA13-Aug-14 1:38
professionalȘtefan-Mihai MOGA13-Aug-14 1:38 
QuestionWhat topics would you like to see explained further? Pin
David Jeske2-Aug-14 7:53
David Jeske2-Aug-14 7:53 
SuggestionRe: What topics would you like to see explained further? [Scene Graphs] Pin
gameengineer17-Dec-14 8:58
gameengineer17-Dec-14 8:58 
GeneralRe: What topics would you like to see explained further? [Scene Graphs] Pin
David Jeske17-Dec-14 11:54
David Jeske17-Dec-14 11:54 
GeneralRe: What topics would you like to see explained further? [Scene Graphs] Pin
gameengineer17-Dec-14 12:21
gameengineer17-Dec-14 12:21 
SuggestionRe: What topics would you like to see explained further? [Assimp integration] Pin
gameengineer17-Dec-14 9:05
gameengineer17-Dec-14 9:05 
GeneralRe: What topics would you like to see explained further? [Assimp integration] Pin
David Jeske17-Dec-14 12:03
David Jeske17-Dec-14 12:03 
QuestionCan't compile Pin
T_uRRiCA_N20-Jul-14 22:41
professionalT_uRRiCA_N20-Jul-14 22:41 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.