Monday, 29 November 2010

A bit of History

Collected 4 boxes of comics from my parents today dating from 1975 - 1981 amongst the other things they found when emptying the loft were a series of print out from what I believe is a pen plotter I had for a commodore 64 computer I would guess these are from around 1983 - 1984 (I was 13 / 14 then) 

The first program draws a spiral, I'm not sure if I wrote this or if it was from one of the user guides, however you can see I wasn't that good at commenting code then.

The next scan seems to be my attempt at doing some kind of 3D drawing but I guess I wasn't happy with it as the code is struck through with biro.
The next scan is a chess board, again don't think this was my one, just a demo (we used to have to type them in then tho, as everything was on a cassette tape backup)
Think I may have been overachieving with this one, the title says "Demo CAD system" unfortunately there is no output so not quite sure what it did, however do remember writing a basic CAD system for my CSE Computer Science course so could have been a version of this (The final one was written for BBC Basic but I don't have it)

Finally I think this may have been some computer homework, as it's the usual class grade calculation (I remember being pissed off of having to do this again when I did my degree ;-) Note the crossings out and comments.

I won't bother to critique the code, but it does look very naive but hey I guess it still works. Will have to try and did out some more old code one day, always fun to look at it.

Sunday, 28 November 2010

GLSL Shader Manager design Part 2

In the previous post I discussed the initial design of the Shader Manager class and outlined the design of the Shader Class. This post will concentrate on the design of the ShaderProgram class which contains the actual Shader sources and be linked and ready to use with GLSL.

The Orange book states

“Each shader object is compiled independently. To create a program,  applications need a mechanism for specifying a list of shader objects to be linked. You can specify the list of shaders objects to be linked by creating a program object and attaching to it all the shader objects needed to create the program”. (Rost 2009)

To this end we need to create an empty program object then attach the existing shaders to the program. The attachment can be made before the shader is compiled, however the Program object can't be linked unless the shaders are compiled. As shaders may be attached to more than one Program we basically need to hold a list of pointers to the shader objects rather than the shaders themselves.

The ShaderProgram will also be the main access point to the shaders once loaded on the GPU so it will have all the methods for accessing the attributes in the program. As OpenGL is a C based library there is no method overloading so we need to implement a method for each of the different accessors, in this cas the class have over 50 methods, however for brevity the class diagram only show the basic ones as seen in the following class diagram.

As part of the design it was also decided to allow attributes in the shader to be bound using a std::string so they could be referenced by name and not the numeric id.

The constructor for the class is as follows

ShaderProgram::ShaderProgram(std::string _name)
  // we create a special NULL program so the shader manager can return
  // a NULL object.
 if (_name !="NULL")
    m_programID = glCreateProgram();
  std::cerr <<"Created program id is "<<m_programid><<"\n";
In the constructor we check for a special name called "NULL" this integrates with the ShaderManager class so we can create an empty default shader object with an ID of 0. GLSL uses the 0 shader to represent the "fixed functionality" pipeline. By default the ShaderManager class will create a NULL shader so that if the named one passed by the user is not found a fixed shader will be returned and calls to this object will not crash the system.

To attach a shader we use the following code

void ShaderProgram::attatchShader(Shader *_shader)

Any number of shaders may be attached to the ShaderProgram, once we are ready we can link the shader

void ShaderProgram::link()
    std::cerr <<"linking Shader "<< m_programName.c_str()<<"\n";
  GLint infologLength = 0;

  std::cerr<<"Link Log Length "<<infologLength<<"\n";

  if(infologLength > 0)
    char *infoLog = new char[infologLength];
    GLint charsWritten  = 0;

    glGetProgramInfoLog(m_programID, infologLength, &charsWritten, infoLog);

    delete [] infoLog;
    glGetProgramiv(m_programID, GL_LINK_STATUS,&infologLength);
    if( infologLength == GL_FALSE)
      std::cerr<<"Program link failed exiting \n";
At present if the link fails the program will exit, I'm not sure if this is actually the best approach but will do for now as this a developmental system.

If we wish to bind the attributes in the shader we can do it before the link of the programs or after however each approach needs a different coding approach. At present binding is only available before linking, however this will be modified in the next version to check the link state and use the appropriate method. Attributes must be specified by the user using a numeric value and the name to be bound. Once this has been done the user may then specify attributes by name only.

void ShaderProgram::bindAttrib(GLuint _index, std::string _attribName)
  if(m_linked == true)
    std::cerr<<"Warning binding attribute after link\n";
  std::cerr<<"bindAttribLoc "<<m_programID<<" index "<<_index<<" name "<<_attribName<<"\n";
Once an attribute is bound we can access it via name using the following functions

bool ShaderProgram::vertexAttribPointer(
                                        const char* _name,
                                        GLint _size,
                                        GLenum _type,
                                        GLsizei _stride,
                                        const GLvoid *_data,
                                        bool _normalise
                                       ) const

  std::map <std::string, GLuint >::const_iterator attrib=m_attribs.find(_name);
  // make sure we have a valid  program
 if(attrib!=m_attribs.end() )
    return  true;
   return false;

void ShaderProgram::vertexAttrib1f(
                                  const char * _name,
                                  GLfloat   _v0
                                  ) const
  std::map <std::string, GLuint >::const_iterator attrib=m_attribs.find(_name);
  // make sure we have a valid  program
 if(attrib!=m_attribs.end() )
    glVertexAttrib1f(attrib->second, _v0);



Accessing Uniforms
To access the uniform data within the shader we need to query the linked program object to get the numeric location of the variable, once this is found we can modify the variable using the OpenGL functions. The following method returns the numeric ID for a uniform and is used in the other functions

GLuint ShaderProgram::getUniformLocation(
                                          const char* _name
                                        ) const
  GLint loc = glGetUniformLocation( m_programID ,_name);
  if (loc == -1)
    std::cerr<<"Uniform \""<<_name<<"\" not found in Program \""<<m_programName<<"\"\n";
  return loc;

Now for every access variable type in OpenGL we can write a method to change the uniform, for example to change a uniform float we use the following code

void ShaderProgram::setUniform1f(
                                  const char* _varname,
                                  float _v0
                                ) const

The rest of the class is rather repetitive code to allow the different attributes and uniforms to be accessed, the next post will look at the overall management class for the Shader system with examples of how it's used.

A Note on std::map
Whilst writing this I found the way I'd been using the std::map could lead to errors. If you consider the following code

#include <iostream>
#include <map>

int main()

  std::map<std::string,int> mymap;
Will print out a size of 2 as expected and we can access the map values using the ["a"] type syntax. However if we do the following
#include <iostream>
#include <map>

int main()

  std::map<std::string,int> mymap;

The program still works but as the key "c" is not know it will output a value of 0 for the line mymap["c"] however it will also insert a new map entry and the 2nd call to mymap.size will return the size 3.
To overcome this behaviour we must use the find method as shown in some of the examples above.
Rost, R, Licea-Kane B (2009). OpenGL Shading Language. 3rd. ed. New York: Addison Wesley.

Saturday, 27 November 2010

GLSL Shader Manager design Part 1

Just been re-writing my lectures for the OpenGL Shading language and decided to re-design my shader manager to be more compliant with the new specification.

When I designed my original system I was using the 1st edition of the Orange Book which I got at a 3D Labs master class in 2004 and is now quite outdated. I've recently go the 3rd edition of the book and read the GLSL API spec and started to design the new system.

The main initial criteria is for it to work as a standalone system without the need of my NGL:: library however it will also be integrated into the library at some stage to replace the existing one and be compatible with the ngl:: datatypes such as Matrix, Vector, Colour etc.

The present system is designed create a single Shader Program by passing in a source file for Vertex, Fragment and optionally a Geometry shader. However the specification says any number of shaders can be created and attached to a Shader Program before compilation. To this end the initial design will separate the Shader and the Program into different classes then have the shader manager contain both the Shaders and the Programs.

Programs will be stored using a std::string name for the user access, and as much as possible the Shader attributes / data values will be accessible via a text string.

GLSL API Process

The following diagram illustrates the basic process of generating shaders and a shader program.
From this process I decided to design the Shader class first as it is a fairly passive class. The outline of the class is as follows.

The main consideration is the class may belong to any number of Shader Programs so a basic reference counting mechanism is being built into the class so the ShaderManager class can see how many references the Shader has, I was initially considering using a boost::shared_ptr class to do this but want to reduce the dependancies on the standalone version. For the eventual ngl integration I may add this as ngl already relies on boost for a number of things.

Shader type is defined as an enum as follows

each shader must be constructed as one of the types which map to the GL data types for shaders. I've added tessellation as an option but don't have a GPU to support it as yet but trying to make things future proof.

The code to create the Shader object is quite simple as follows

                std::string _name,
                SHADERTYPE _type
  m_shaderType = _type;
  m_debugState = true;
  switch (_type)
    case VERTEX : { m_shaderHandle = glCreateShader(GL_VERTEX_SHADER_ARB); break; }
    case FRAGMENT : { m_shaderHandle = glCreateShader(GL_FRAGMENT_SHADER_ARB); break; }
    case GEOMETRY : { m_shaderHandle = glCreateShader(GL_GEOMETRY_SHADER_EXT); break; }
    case TESSELATION : { m_shaderHandle = NULL; std::cerr<<"not yet implemented\n"; }
  m_compiled = false;
The handle returned from the glCreateShader function is the one used by OpenGL for the rest of the stages.

To load the source we use a std::string and a nice 1 liner using the istream iterator as follows

void Shader::load(
                   std::string _name
  // see if we already have some source attached
  if(m_source !=0)
    std::cerr<<"deleting existing source code\n";
    delete m_source;
  std::ifstream shaderSource(_name.c_str());
  if (!shaderSource.is_open())
   std::cerr<<"File not found "<<_name.c_str()<<"\n";
  // now read in the data
  m_source = new std::string((std::istreambuf_iterator<char>(shaderSource)), std::istreambuf_iterator<char>());

  const char* data=m_source->c_str();
  glShaderSource(m_shaderHandle , 1, &data,NULL);

  if (m_debugState == true)
    std::cerr<<"Shader Loaded and source attached\n";

Once this is loaded we can compile the shader using the following commands
void Shader::compile()
  if (m_source == 0)
    std::cerr<<"Warning no shader source loaded\n";
  std::cerr <<"Compiling Shader "<<m_name<<"\n";

This is about it for the Shader class, I decided to keep the shader source as part of the class but it's not needed once attached to the shader so will perhaps write methods to allow the deletion of the source to save space once the shader is compiled.

The next instalment will look at the ShaderProgram class, in the meantime the full source and demo program is available with the lecture notes here in Lecture 8

Thursday, 18 November 2010

Installing NGL docs in Qt

The following post explains how to create the doxygen help for NGL then install it into QtCreator

First we need to create a directory for the help. Change into the NGL directory and type the following

mkdir docs
mkdir docs/html

Next in the root directory of NGL type doxygen (and ignore the warnings !)

This should generate all the html help files for doxygen. We now need to convert them into a format that Qt uses. This is done with the qhelpgenerator program which is located in  /opt/qtsdk/qt/bin/qhelpgenerator

To use it we change to the $(HOME)/NGL/docs/html directory and run

 /opt/qtsdk/qt/bin/qhelpgenerator index.qhp

This will create a file called index.qch which is loaded into Qt Creator, open up the preferences and locate the following tab

click on the add button and locate the NGL/docs/html/index.qch and add it.

re-start Qt Creator and you should be able to press F1 on any of the NGL:: classes and get the help as shown below

QtCreator 2.1 beta-2

Just downloaded QtCreator 2.1 beta-2 from here and it seems to work quite well. It's added a feature I've been looking for for ages which is syntax highlighting of non C++ files, to configure it you need to do the following.

First open up the preferences and go to the editor section and choose the generic highlighter section

Next select the download definitions and choose which ones you want (I chose Python and GLSL) as shown

This will download the file into the directory $(HOME).config/Nokia/qtcreator/generic-highlighter and for glsl it is a file called glsl.xml. I usually name my Vertex shaders with a .vs extension and my Fragment shaders with a .fs extension so we need to add this to the xml file

<language name="GLSL" section="Sources" extensions="*.glsl;*.vert;*.frag;*.vs;*.fs" mimetype="text/x-glslsrc" version="1.02" kateversion="2.4" author="Oliver Richers (" license="LGPL">

Now all we need to do is re-start QtCreator and we have syntax highlighted glsl ;-)

Monday, 15 November 2010

Interpolation (3 different ones)

Just been writing tomorrow's lecture on interpolation and decided to write a simple function to demonstrate the 3 different types I would be using. Most of the maths in this post is based on the Excellent "Mathematics for Computer Graphics" by John Vince every computer graphics person should own this book it's only £20.

Linear Interpolation

We can use linear interpolation to blend between two values using a floating point scalar value which ranges from 0-1

The basic formula given two values a and b and a real number t is \(
p=a+(b-a)*t \text{ where } 0\leq t\leq1 \). If we overload operators for our vector class so that we can subtract a vector from a vector, add a vector to a vector and multiply by a floating point scalar we can implement a Lerp function as

def Lerp(self, _a, _b, _t) :
  return _a+(_b-_a)*_t

In C++ it makes sense to make this a template function and the ngl:: library contains this template

/// @brief a simple template function for Linear Interpolation requires that any classes have
///    + - and * scalar (i.e. Real) overloaded operators
///    In the graphics lib this will work  for Vector and Colour
/// @param [in] _a the template value for the first parameter
/// @param [in] _b the template value for the first parameter
/// @param [in] _t the value for the blend between _a and _b must be between 0 - 1
template <class T> T lerp(
                          T _a,
                          T _b,
                          ngl::Real _t
 T p;
 return p;
And the C++ version can be used by including Util.h as follows
#include "ngl/Util.h"

ngl::Colour c1(0.0,0.0,0.0);
ngl::Colour c2(1.0,0.0,0.0);
ngl::Colour c3=Lerp(c1,c2,0.3);

ngl::Vector v1(1.0,2.0,1.0);
ngl::Vector v2(1.0,0.0,2.0);
ngl::Colour v3=Lerp(v1,v2,0.3);

Trigonometric Interpolation
A Linear interpolant ensures that equal steps in the parameter t give rise to equal steps in the interpolated values. However it is often required that equal steps in t give rise to unequal steps in the interpolated values. We can achieve this using a variety of mathematical techniques.

From the basic trigonometric ratios we know that \(\sin^2\beta+\cos^2\beta=1\) This satisfies one of the requirements of an interpolant that the terms must sum to 1. If \(\beta\) varies between 0 and \(\frac{\pi}{2}\) then \(\cos^2\beta\) varies between 1 and \(\sin^2\beta\) varies between 0 and 1 which can be used to modify the interpolated values. We can write this as

$$n=n_1\cos^2t+n_2\sin^2t \text{ where } \left[0 \leq t \leq \frac{\pi}{2} \right] $$
plotting these values we get the following curves
If we calculate this for a point starting at (1,1) and ending at (4,3) we get the following graph

You will notice that the path along the line is now non-linear, to write a Trigonometric interpolation function we need to form our values to range from 0-90 for a range of 0.0 - 1.0, further to this we need to convert these values to radians.
def TrigInterp(self, _a,_b,_t) :
  return _a*math.cos(angle)*math.cos(angle)+_b*math.sin(angle)*math.sin(angle)
Cubic Interpolation
In cubic interpolation we need to develop a cubic function to do our blending.
In mathematics a cubic function is one of the form
Applying this to our interpolant we get
or in Matrix form
$$n=\left[ v_{1} v_{2}\right]\left[\begin{array}{c} n_{1} \\ n_{2}\end{array}\right]$$

The task is to find the values of the constants associated with the polynomials v1 and v2
The requirements are

  1. The cubic function v2 must grow from 0 to 1 for 
  2. The slope at point t must equal the slope at the point (1-t) this ensures the slope symmetry over the range of the function
  3. The value v2 at any point t must also produce (1-v2) at (1-t) this ensures curve symmetry
To satisfy the first requirement :

and when \(t=0\), \(v_2=0\) and \(d=0\). Similarly, when \(t=1\), \(v_2=a+b+c\).

To satisfy the second requirement, we differentiate \(v_2\) to obtain the slope
$$ \frac{dv_2}{dt}=3at^2+2bt+c=3a(1-t)^2+2b(1-t)+c $$
equating the constants we discover \(c=0\) and \(0=3a+2b\)

To satisfy the third requirement
where we can compute \(1=a+0\). But \(0=3a+2b\), therefore \(a=2\) and \(b=3\) and we get
We must now find the previous curve's mirror, which starts at 1 and collapses to 0 as \(t\) moves from 0 to 1. To do this we subtract the previous equation from 1 and get
These can be used as the interpolants
$$n=\left[ \begin{array}{cc} 2t^3-3t^2+1 & -2t^3+3t^2\end{array}\right]
\left[\begin{array}{c} n_1\\n_2\end{array}\right]$$
expanded in matrix form to
$$n=\left[ \begin{array}{cccc} t^3 & t^2 & t &1 \end{array}\right]
2 & -2 \\
-3 & 3 \\
0 & 0 \\
1 & 0 \\

\left[\begin{array}{c} n_1\\n_2 \end{array}\right]$$

Plotting the two sets of polynomials gives us the following curves

applying this to the points (1,1) to (4,3) over a range 0-1 we get the following point spread

We can write a function to do this as follows

def Cubic(self, _a,_b,_t) :
  return (_a*v1)+(_b*v2)

The following movie shows all 3 functions in action on a teapot, the top one is Trigonometric interpolation, the middle linear interpolation and the bottom one Cubic

You can see the ease in / out effect of the two non-linear interpolants and the linear one moving at a constant rate.

Vince, John (2010). Mathematics for Computer Graphics. 2nd. ed. London: Springr Verlag.

Math Test

Just followed this post and now have maths working in the blog ;-)

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

Saturday, 13 November 2010

Making Things OpenGL 3/4.x compatible (Initial Design Considerations)

Have been re-reading the OpenGL quick reference card again and looking at all the elements that have been deprecated. It would seem that most of the light / material elements have been removed from the "core profile"

As a handy reminder the quick reference card highlights the elements being removed in blue and for this initial design post I'm going to concentrate on the Light / Material / Colour properties here

As you can see all of the Light / Colour elements have been deprecated as well as the materials, this means that we will no longer have any access to these elements in the shader and structures such as gl_LightSource and the colour elements such as gl_FrontMaterial.

So we need to be able to pass both light and colour information to our Fragment shader and then use this in the calculations. This sounds a bit similar to how renderman works so I decided to design the initial system around renderman's lighting model.

In renderman we have a single colour for basic plastic surfaces and access to a global variable called Cs which describes the surface colour (either set by the Color [1,0,0] command or calculated in the shader itself). A full list of these variables are shown in the table below (from the RPS_15 user guide)

The basic renderman shader execution environment is as follows

Whilst we will not have all these variables available in the GLSL shader we can imitate most of it, and make our lights behave in a similar way to the renderman ones. 

The scans below illustrate my initial sketches of a Light class system to add to the new version of ngl:: 

Writing this up more formally I've have this as the initial design of the Light classes

This is going on the back burner for a while as I have loads of other elements to sort out but at least I can bear this in mind whilst re-writing some other parts of ngl::.

SpotLight part two

Got quite a lot of progress yesterday on the spotlight demo will write it up soon, just need to get the falloff sorted

Here's a load of teapots

Friday, 12 November 2010

Spotlight Shader work in progress

Just got the basic spotlight shader working,

here's a quick demo, in meetings all day ;-( so doubt I'll get a chance to update it till Monday

Thursday, 11 November 2010

Imitating OpenGL Fixed functionality pipeline in OpenGL 4.x (Part 2)

So as explained in the previous post I've decided to write a shader to imitate the OpenGL fixed functionality shading pipeline in GLSL, I started simply with getting the OpenGL 4.x transforms working and this is the result of an unshaded scene with translations and rotations working

Now we have to add some code to calculate the fragmentNormal and some values for the eye co-ordinates for the shader, our final Vertex shader is 
/// @brief projection matrix passed in from camera class in main app
uniform mat4 projectionMatrix;
/// @brief View transform matrix passed in from camera class in main app
uniform mat4 ViewMatrix;
/// @brief Model transform matrix passed in from Transform Class in main app
uniform mat4 ModelMatrix;
/// @brief flag to indicate if model has unit normals if not normalize
uniform bool Normalize;
/// @brief flag to indicate if we are using texturing
uniform bool TextureEnabled;
varying vec3 fragmentNormal;
/// @brief the vertex in eye co-ordinates non homogeneous
varying vec3 eyeCord3;
/// @brief the number of lights enabled
uniform int numLightsEnabled;
/// @brief the eye position passed in from main app
uniform vec3 eye;

void main(void)
 // pre-calculate for speed we will use this a lot
 mat4 ModelView=ViewMatrix*ModelMatrix;
 // calculate the fragments surface normal
 fragmentNormal = (ModelView*vec4(gl_Normal, 0.0)).xyz;

 if (Normalize == true)
  fragmentNormal = normalize(fragmentNormal);

 // calculate the vertex position
 gl_Position = projectionMatrix*ModelView*gl_Vertex;
 // Transform the vertex to eye co-ordinates for frag shader
 /// @brief the vertex in eye co-ordinates  homogeneous
 vec4 eyeCord;
 // divide by w for non homogenous
 if (TextureEnabled == true)
   gl_TexCoord[0] = gl_TextureMatrix[0]*gl_MultiTexCoord0;


So next to write the Fragment shader to set the colour / shading properties of the elements being processed. 

Most of this posting is based on the Orange book (OpenGL Shading Language 1st Edition Randi J. Rost)

The output of the fragment shader is to set the fragment colour, and with most lighting models this is based on a simple lighting model where we have the following material properties
  1. Ambient contribution an RGB colour value for ambient light
  2. Diffuse contribution an RGB colour value for the diffuse light (basic colour of the model)
  3. Specular contribution an RGB colour value for the specular highlights of the material
In the shader we use the following code
vec4 ambient=vec4(0.0);
vec4 diffuse=vec4(0.0);
vec4 specular=vec4(0.0);

//calculate values for each light and surface material

gl_FragColor = ambient+diffuse+specular;

We now need to loop for every light in the scene and accumulate the total contribution from each and set the final fragment colour.

Directional Lights
Directional Lights are the simplest lighting model to compute as we only pass a vector indicating the lighting direction to the shader. OpenGL only has two basic lights one called a light the other a spotlight, to differentiate between Directional lights and Point lights OpenGL uses a homogenous vector to indicate which light to use. 

Usually in CG we specify a Point and a Vector using a 4 tuple V=[x,y,z,w] where the w component is to indicate if we have a point or a vector. We set w=0 to indicate a vector and w=1 to indicate a point, and thus setting w=0 we have a Directional light. We can add this to the shader code as follows
if(gl_LightSource[i].position.w ==0.0)

This depends upon the gl_LightSource[] built in structure which is defined as follows

struct gl_LightSourceParameters
 vec4 ambient;              
 vec4 diffuse;              
 vec4 specular;             
 vec4 position;             
 vec4 halfVector;           
 vec3 spotDirection;        
 float spotExponent;        
 float spotCutoff;          
 float spotCosCutoff;       
 float constantAttenuation; 
 float linearAttenuation;   
 float quadraticAttenuation;

uniform gl_LightSourceParameters gl_LightSource[gl_MaxLights];

*Note after re-reading the spec this has also been marked for deprecation so this will have to be replaced in the next iteration !

This structure is passed data from the OpenGL glLight mechanism and the existing ngl::Light class will set these value for us.

So using these values we can write the code for the Directional light function as follows
/// @brief a function to compute point light values
/// @param[in] _light the number of the current light
/// @param[in] _normal the current fragmentNormal
/// @param[in,out] _ambient the ambient colour to be contributed to
/// @param[in,out] _diffuse the diffuse colour to be contributed to
/// @param[in,out] _specular the specular colour to be contributed to

void directionalLight(
            in int _light,
            in vec3 _normal,
            inout vec4 _ambient,
            inout vec4 _diffuse,
            inout vec4 _specular
 /// @brief normal . light direction
 float nDotVP;
 /// @brief normal . half vector
 float nDotHV;
 /// @brief the power factor
 float powerFactor;
 // calculate the lambert term for the position vector
 nDotVP= max(0.0, dot(_normal, normalize(vec3 (gl_LightSource[_light].position))));

 // now see if we have any specular contribution
 if (nDotVP == 0.0)
  powerFactor = 0.0; // no contribution
         // and for the half vector for specular
          nDotHV= max(0.0, dot(_normal, vec3 (gl_LightSource[_light].halfVector)));
  // here we raise the shininess value to the power of the half vector
  // Phong / Blinn shading method
  powerFactor = pow(nDotHV, gl_FrontMaterial.shininess);
 // finally add the lighting contributions using the material properties
 // diffuse is calculated by n.v * colour
 // compute the specular value

This function can be broken down into the following steps

  1. Calculate the diffuse contribution using Lambert law
  2. Calculate the specular contribution using the half way vector (Phong / Blinn)
  3. Calculate the ambient contribution (just add the ambient light values to the ambient material properties
To calculate the diffuse we take the dot product of the fragmentNormal with the normalized version of the light position vector the result of this will be multiplied by the material diffuse property to calculate the diffuse colour.

Next we determine if we have any specular contribution, if the diffuse is 0 then we have not contribution so we set the  powerFactor to 0 and specular will not be added.

If we do we calculate the dot product of the fragmentNormal and the pre-calculated by OpenGL halfway Vector, this is then raised to the power of the specularExponent which is passed as the shininess parameter of the material.

Finally we calculate the colours and return them to the main light loop

The following image shows two directional lights shading the scene and you can see the direction of the two highlights for the two different sources.

Point Light
The point light is an extension of the directional light and adds in attenuation over distance as well as calculating the direction of the maximum highlight for each vertex rather than using the halfway vector.

The following code shows this shader
/// @brief a function to compute point light values
/// @param[in] _light the number of the current light
/// @param[in] _normal the current fragmentNormal
/// @param[in,out] _ambient the ambient colour to be contributed to
/// @param[in,out] _diffuse the diffuse colour to be contributed to
/// @param[in,out] _specular the specular colour to be contributed to

void pointLight(
        in int _light,
        in vec3 _normal,
        inout vec4 _ambient,
        inout vec4 _diffuse,
        inout vec4 _specular
 /// @brief normal . light direction
 float nDotVP;
 /// @brief normal . half vector
 float nDotHV;
 /// @brief the power factor
 float powerFactor;
 /// @brief the distance to the surface from the light
 float distance;
 /// @brief the attenuation of light with distance
 float attenuation;
 /// @brief the direction from the surface to the light position
 vec3 VP;
 /// @brief halfVector the direction of maximum highlights
 vec3 halfVector;

 /// compute vector from surface to light position
 // get the distance from surface to light
 // calculate attenuation of light through distance
 attenuation= 1.0 / (gl_LightSource[_light].constantAttenuation +
                      gl_LightSource[_light].linearAttenuation * distance +
                      gl_LightSource[_light].quadraticAttenuation * distance *distance);

 // calculate the lambert term for the position vector
 nDotVP= max(0.0, dot(_normal,VP));
 // and for the half vector for specular
 nDotHV= max(0.0, dot(_normal, halfVector));

 // now see if we have any specular contribution
 if (nDotVP == 0.0)
  powerFactor = 0.0; // no contribution
  // here we raise the shininess value to the power of the half vector
  // Phong / Blinn shading method
  powerFactor = pow(nDotHV, gl_FrontMaterial.shininess);
 // finally add the lighting contributions using the material properties
 // diffuse is calculated by n.v * colour
 // compute the specular value

The main difference in this function is the calculation of the vector VP which is the vector from the surface to the light position, we then calculate the length of this to determine the distance of the light from the point being shaded. This will be used in the attenuation calculations to make the light strength weaker as the fragment is further away from the light.

The following image show the basic pointLight in action with two lights placed in the scene one above the sphere and the other over the cube.

self.Light0 = Light(Vector(-3,1,0),Colour(1,1,1),Colour(1,1,1),LIGHTMODES.LIGHTLOCAL)
self.Light1 = Light(Vector(0,1,3),Colour(1,1,1),Colour(1,1,1),LIGHTMODES.LIGHTLOCAL)

We set the attenuation of the light using the setAttenuation method which has the following prototype
/// @brief set the light attenuation
/// @param[in] _constant the constant attenuation
/// @param[in] _linear attenuation
/// @param[in] _quadratic attenuation
  void setAttenuation(
                       const Real _constant=1.0,
                       const Real _linear=0.0,
                       const Real _quadratic=0.0

Imitating OpenGL Fixed functionality pipeline in OpenGL 4.x (Part 1 of many)

So when converting some of my demos I decided to do the spotlight demo from last year, this uses the built in OpenGL spotlight and the normal fixed functionality OpenGL pipeline.

This year I've ported all of my code to the newer 3.x / 4.x OpenGL pipeline which as deprecated a number of gl commands ( a full list are here) but the core to most of the initial work is in the follow section from Appendix E or the document

Begin / End primitive specification - Begin, End, and EdgeFlag* (sec- tion 2.6.1); Color*, FogCoord*, Index*, Normal3*, SecondaryColor3*, TexCoord*, Vertex* (section 2.7); and all associated state in tables 6.4 and 6.5. Vertex arrays and array drawing commands must be used to draw primitives.

(section 2.8); Frustum, LoadIdentity, LoadMatrix, LoadTransposeMatrix, MatrixMode, Mult- Matrix, MultTransposeMatrix, Ortho, PopMatrix, PushMatrix, Ro- tate, Scale, and Translate 

What this basically means is the immediate mode OpenGL is no longer core to OpenGL 3/4 and we must use the GPU as much as possible. Most of this work involves the OpenGL matrix stack and the use of immediate mode, which is slow and inefficient and not available in OpenGL ES (used for mobile devices such as iPhone).

NGL already supports the use of GLSL shaders and with the ngl::Transform and ngl::TransformStack classes we can do all of the glRotate, glTranslate, glScale functions as well as the glPush/PopMatrix commands.

There are also methods built into the Transform / TransformStack to load these matrix values to a shader to use in GLSL. 

For example in fixed functionality OpenGL each call to glVertex will pass through the following processes

This is easy to implement as the ngl::Camera class will calculate these values based on our Virtual Camera configuration of Eye, Look and Up (for the View matrix) and Current Transform Stack for the  Model element of the ModelView matrix combination.

The projection is also calculated in the camera class and loaded to the shader. The following Vertex shader shows the calculaition of the current Vertex based on these values as well as the fragment normal.
uniform mat4 projectionMatrix;
uniform mat4 ViewMatrix;
uniform mat4 ModelMatrix;

varying vec3 fragmentNormal;
varying mat4 transform;

void main(void)
  fragmentNormal = (ViewMatrix*ModelMatrix*vec4(gl_Normal, 0.0)).xyz;
  gl_Position = transform*gl_Vertex;

In the above example the uniform mat4 variables are passed to the shader from our program and represent the current state of the MODELVIEW and PROJECTION matrices at the time of the vertex processing. For example usually we would set the projection of the camera and the view from the camera once a frame (or if fixed at the start of the program), then the modelling transformations of the current set of vertices will be set to position our objects as show in the following configuration code.
ngl::Vector From(0,0,8);
ngl::Vector To(0,0,0);
ngl::Vector Up(0,1,0);

m_cam= new ngl::Camera(From,To,Up,ngl::PERSPECTIVE);
// set the shape using FOV 45 Aspect Ratio based on Width and Height
// The final two are near and far clipping planes of 0.5 and 10
// now to load the shader and set the values
// grab an instance of shader manager
ngl::ShaderManager *shader=ngl::ShaderManager::instance();
// load a frag and vert shaders
// set this as the active shader
// now pass the modelView and projection values to the shader

This will basically set up a static view similar to the standard gluLookAt function, any modelling transformation such as Push/Pop matrix and glRotate / glTranslate / glScale are loaded to the Model part of the matrix when drawing as show in the following code segment
ngl::Transformation trans;
// set this in the TX stack
// now set this value in the shader for the current ModelMatrix

// get the VBO instance and draw the built in teapot
ngl::VBOPrimitives *prim=ngl::VBOPrimitives::instance();

} // and before a pop

So far so good, we can view, transform and project our models using OpenGL 3/4.x and this system is on the GPU (thanks to the ngl::VBOPrimitives class which wraps our data onto the GPU and mimics a lot of the glut primitives which are all immediate mode gl)

Next we need to look at lighting and material properties and how to shade everything. This is where it get complicated, and will be in the next post.

Wednesday, 10 November 2010

Updating NGL Demos

Been updating some of the demo code I use for this years lectures been quite useful doing the Python and C++ API at the same time as it's highlighted a few bugs in the system and I've cleaned up a load of silly C++ code that makes no real sense in the Python implementation.

Been finding prototype in Python quite quick and when I transfer from one system to the other it's actually fairly quick (usually just changing -> to . and the odd ::)

Managed to do two demos so far one for Lighting and one showing how the primitives work, going to do the spotlight next

Here's a couple of images

Tuesday, 9 November 2010

refactoring fun (not)

Finally re-factor all the NGL code to match the Qt method standard using lower case first word then Camel case for each following word.

First time round it went really wrong as I mended a couple of const bugs at the same time breaking most of the code.

So thanks to bzr I managed to revert the code and do one thing at a time correctly. The new version seems to work well and the coding standard has been updated to reflect the changes. Not bad for a day's work

Here is a simple python NGL program to draw a teapot using the new style

import math
import pdb
from OpenGL.GL import *
from OpenGL.GLU import *
from PyQt4 import QtGui
from PyQt4.QtOpenGL import *
from PyQt4.Qt import Qt
from PyQt4 import QtCore
from PyNGL import *
import sys
import random

class GLWindow(QGLWidget):

 def __init__(self, parent):
   QGLWidget.__init__(self, parent)
   self.setMinimumSize(1024, 720)
   self.m_spinYFace = 0
   self.m_spinXFace = 0
   self.m_origX = 0
   self.m_origY = 0

 def mousePressEvent (self,  _event) :

  # this method is called when the mouse button is pressed in this case we
  # store the value where the maouse was clicked (x,y) and set the Rotate flag to true
  if(_event.button() == Qt.LeftButton) :
   self.m_origX = _event.x();
   self.m_origY = _event.y();
   self.m_rotate =True;

 def mouseMoveEvent ( self,_event ) :
  # note the method buttons() is the button state when event was called
  # this is different from button() which is used to check which button was
  # pressed when the mousePress/Release event is generated
  if(self.m_rotate and _event.buttons() == Qt.LeftButton) :
   self.m_spinYFace = ( self.m_spinYFace + (_event.x() - self.m_origX) ) % 360
   self.m_spinXFace = ( self.m_spinXFace + (_event.y() - self.m_origY) ) % 360
   self.m_origX = _event.x();
   self.m_origY = _event.y();
   # re-draw GL

 def mouseReleaseEvent (self,  _event) :

  # this event is called when the mouse button is released
  # we then set Rotate to false
  if (_event.button() == Qt.LeftButton) :

 def paintGL(self):
   Drawing routine

   # set the mouse rotation
   # set this in the TX stack




 def resizeGL(self, w, h):
   Resize the GL window
   glViewport(0, 0, w, h)

 def initializeGL(self):
   Initialize GL
   # set viewing projection
   glClearColor(0.4, 0.4, 0.4, 1.0)

   # load a frag and vert shaders
   # set this as the active shader
   # now pass the modelView and projection values to the shader

   self.Light0 = Light(Vector(5,12,0,1),Colour(1,1,1),Colour(1,1,1),LIGHTMODES.LIGHTLOCAL)

# You don't need anything below this
class NGLOpenGLDemo(QtGui.QMainWindow):

 def __init__(self):
  self.widget = GLWindow(self)

 def keyPressEvent(self ,_event) :

  if _event.key() == Qt.Key_Q :
  elif _event.key() == Qt.Key_W :
  elif _event.key() == Qt.Key_S :
  elif _event.key() == Qt.Key_Up :
  elif _event.key() == Qt.Key_Down :
  elif _event.key() == Qt.Key_Left :
  elif _event.key() == Qt.Key_Right :

  elif _event.key() == Qt.Key_I :
  elif _event.key() == Qt.Key_O :


if __name__ == '__main__':
 app = QtGui.QApplication(['Simple NGL Python Demo'])
 window = NGLOpenGLDemo()
 window.setWindowTitle("PyNGL Demo")

This program relies on two shaders to do basic transformations and blinn style shading. The Vertex shader is as follows

uniform mat4 projectionMatrix;
uniform mat4 ViewMatrix;
uniform mat4 ModelMatrix;

varying vec3 fragmentNormal;

void main(void)
  fragmentNormal = (ViewMatrix*ModelMatrix*vec4(gl_Normal, 0.0)).xyz;
  gl_Position = projectionMatrix*ViewMatrix*ModelMatrix*gl_Vertex;

This shader is passed the values calculated for the projection (from the NGL::Camera class) as well as the Model and View transformations.
It will calculate the position of the vertex as well as the fragment normal (based on the normal passed for shading from the teapot model in this case)

The actual shading is done in the fragment shader below

/// @brief[in] the vertex normal
varying vec3 fragmentNormal;

void main ()
  // set the output colour to black
  vec4 colour= vec4(0.0);
  // normalize the vertex normal
  vec3 N = normalize(fragmentNormal);
  // The Light source vector
  vec3 L;
  // the Halfway vector (used for speed)
  vec3 H;
  // pre declare the colour contribution values
  vec4 ambient;
  vec4 diffuse;
  vec4 specular;

  // get the Light vector
  L = normalize(gl_LightSource[0];
  // get the halfway vector
  H = normalize(gl_LightSource[0];
  // ambient just added
  ambient = gl_FrontMaterial.ambient *gl_LightSource[0].ambient;
  // calculate diffuse based on Lambert's law (L.N)
  diffuse = gl_FrontMaterial.diffuse  *gl_LightSource[0].diffuse * max(dot(L, N), 0.0);
  // calculate specular based on H.N^Shininess
  specular = gl_FrontMaterial.specular *gl_LightSource[0].specular * pow(max(dot(H, N), 0.0), gl_FrontMaterial.shininess);
  // combine contribution for the light
  // finally set the colour clamping between 0 and 1
  gl_FragColor = clamp(vec4(colour),0.0,1.0);


This shader calculates the shading values based on the 1st GL light in the scene. It calculates ambient diffuse and specular contributions based on the current openGL material passed from the NGL::Material class.

We use a basic diffuse / lambert shading model for the diffuse contribution and the half way vector for the specular shading to mimic Phong / Blinn reflections.

And finally a golden teapot

Sunday, 7 November 2010

Retrofitting a Qt Layout

I've been re-visiting my AffineTransforms demo to add a GUI to it, I quickly created a suitable ui in Qt Designer and got the program running.

Problem was when I re-sized the window this happens

As you can see the main window re-sizes but the child widgets are the same size. This is the default procedure and I needed to add a layout manager to the ui, "simple I thought", then oh no it isn't, after lots of  RTFM and finding this post I finally managed to get this

First off you need to think about how the UI should look and what you are actually trying to achieve,  Qt has 4 main layout options Form and Grid are the main ones for the type of UI I was going for (decided the splitter one was not really applicable to this project).

So I clicked on the central widget for the main window and tried the formLayout and this happened

No really what I wanted, "oh well lets try the Grid Layout"

Slightly better but still not right, however if you start moving widgets around they sort of locks in place and I ended up with this

Originally I had a QFrame widget with the OpenGL window placed into as a child using this code
// now we create our glwindow class
m_gl = new GLWindow(m_ui->m_glFrame);

However for some reason this doesn't work and the GLWindow doesn't get the re-size or parenting to the frame (I'm presuming as it's not added to a layout it doesn't get the re-size event)
So I decided to "read the source" and see what the uic produced in the .h file from the form.

m_glFrame = new QFrame(m_centralwidget);

gridLayout_6->addWidget(m_glFrame, 0, 0, 5, 6);

gridLayout_6 WTF is that? It turns out that as I've been fighting with the designer this was the 6th grid widget I'd created and not named it. So I searched in the Object viewer only to not find this layout. WTF again! Finally I found that the layout was hidden here
So I renamed it to s_mainGridLayout ( s_ as it's effectively a static member I tend to call all  ui elements s_  when they are not modified by the code being written despite the fact that the Qt engine does) and I can now access it in my code, so to create the GLWindow I just need to do the following 

// now we create our glwindow class
m_gl = new GLWindow(this);
m_ui->s_mainGridLayout->addWidget(m_gl, 0, 0, 6, 6);

Where the addWidget command is prototyped as
void QGridLayout::addWidget ( QWidget * widget, int fromRow, int fromColumn, int rowSpan, int columnSpan, Qt::Alignment alignment = 0 )

As we have 6 widgets across the bottom of the screen (the controls for choosing the model etc) this is the size we need.

This seems to work now,  finally all I had to do was to ensure the other container widgets didn't re-size as the main window is changed, to do this we set the size policy of the container widgets
So what have I learnt?
  1. Always set the main widget layout before adding other elements
  2. Use containers within containers for layouts
  3. retrofitting is a pain ;-)
Finally a teapot

Saturday, 6 November 2010

OpenGL Programming Guide for Mac OS X

Just found a link to this page on

It's a really good document with lot of generic OpenGL stuff as well as mac specific. I think these two sections will be appearing in lecture notes very soon

Best Practices for Working with Vertex Data
Best Practices for Working with Texture Data 

To re-factor or not to re-factor

That is the Question,

For the last few years I've been making the students work to a coding standard (by giving them a small amount of marks for doing so). This has a number of advantages

  1. All the code looks the same and makes it easier to integrate into a larger code base.
  2. Makes spotting plagiarism easier (especially with the citation rules)
  3. Prepares the students for real life working situations (our coding standard is based on two real world examples)
When the original standard was published the code base for ngl was based on OpenGL and SDL however this year it has all been ported to Qt as this seems to be the new standard for most animation apps.

The problem I now face comes from this section in the standard

Function Names

Function names have the first letter of each world capitalised, with no underscores between words.
For Example:

Where possible, functions/methods that return a bool result should have a name that looks like a question, eg
IsValid, HasProtocol, AreParallel...
Each function should be preceeded by a comment containing a brief description about the function (how it works, what it does) above the function body in the .cpp file.

All of the Methods  in ngl follow this rule, however when using Qt the following is the standard syntax

This means we have a mixed standard in most programs, I could re-factor the ngl: lib but this would take a while and break quite a lot of legacy code (which is still in the process of being re-written anyway).

At the present my thoughts are

Positives :

  1. Makes all the code look the same and matches Qt style
  2. Will not confuse people when writing code as it will always be the same 
  3. quite like the looks of the Qt syntax
  4. Not issued much code to the students yet, and start the main NGL teaching in a couple of weeks
Negatives :
  1. I will take quite a while to convert things
  2. Could break quite a lot of old code
  3. I'm actually used to using the current method and would have to re-learn how I write things
  4. The actual Qt guidelines are not that good so can't use them wholsale 
Think I will wait until Monday and decide then.

Jon's Teapot

After a lunch time design meeting (in the Ship) Luiz decided that the name Jon's coding blog was crap, so after much discussion it was decided to call this blog "Jon's Teapot". The main motivation for this is the fact that most of my demos include some form of Utah Teapot, and it is also an oblique reference to Russell's teapot as well.

The image above was created using Renderman Python using a simple Fractional Brownian motion (fBM) displacement shader

displacement fbmDisp
 float Km=0.1;
 float Layers=6;
 output varying float Freq=1;

/* init the shader values */
vector NN=normalize(N);
float i;
float mag=0;
point Pt=transform("shader",P);
for(i=0; i<Layers; i+=1)
  mag+=(float noise(Pt*Freq)-0.5)*2/Freq;
mag /=length(vtransform("object",NN));


The basic scene was created using a Python for Renderman script below, this script is a two stage script which generates shadow maps by moving the camera to the position of each of the lights and rendering a Z depth map which the special shadowspot shader uses to calculate the occlusion.

Once these maps are generated the final scene is rendered using these maps.

# for bash we need to add the following to our .bashrc
import getpass
import time,random,math
# import the python renderman library
import prman

# Modified from Renderman Examples in The renderman Companion
# AimZ(): rotate the world so the direction vector points in
# positive z by rotating about the y axis, then x. The cosine
# of each rotation is given by components of the normalized
# direction vector.  Before the y rotation the direction vector
# might be in negative z, but not afterward.

def AimZ(ri,direction) :
 if (direction[0]==0 and direction[1]==0 and direction[2]==0) :
 # The initial rotation about the y axis is given by the projection of
 # the direction vector onto the x,z plane: the x and z components
 # of the direction.

 xzlen = math.sqrt(direction[0]*direction[0]+direction[2]*direction[2])
 if (xzlen == 0) :
  if(direction[1] <0) :
   yrot = 0
  else :
   yrot =180

 #  yrot = (direction[1] < 0) ? 180 : 0
 else :
  yrot = 180*math.acos(direction[2]/xzlen)/math.pi;

  # The second rotation, about the x axis, is given by the projection on
  # the y,z plane of the y-rotated direction vector: the original y
  # component, and the rotated x,z vector from above.

 yzlen = math.sqrt(direction[1]*direction[1]+xzlen*xzlen)
 xrot = 180*math.acos(xzlen/yzlen)/math.pi  # yzlen should never be 0

 if (direction[1] > 0) :
  ri.Rotate(xrot, 1.0, 0.0, 0.0)
 else :
  ri.Rotate(-xrot, 1.0, 0.0, 0.0)
 #The last rotation declared gets performed first
 if (direction[0] > 0) :
  ri.Rotate(-yrot, 0.0, 1.0, 0.0)
 else :
  ri.Rotate(yrot, 0.0, 1.0, 0.0)

def ShadowPass(ri,Name,From,To,coneAngle,SceneFunc) :
 print "Rendering Shadow pass %s.z" %(Name)
 ri.Display(Name+".z", "zfile", "z")
 # Specify PAL resolution 1:1 pixel Aspect ratio
 # now set the projection to perspective
 #now move to light position
 # create a vector for the Spotlight to and from values

 # to do this we subtract each of thelist elements using a lambda function
 # this is the same as doing the code below I will leave it to you as to which you
 # find more readable
 #direction =[To[0]-From[0],To[1]-From[1],To[2]-From[2]]

 direction = map(lambda x,y : x-y , To,From)
 # now draw the Scene
 print " Done MakeShadow %s.shad" %(Name)

def Scene(ri) :
 ri.Translate( 0,-1.0,0)
 ri.Displacement("fbmDisp",{"float Km":[0.2]})

 face=[-0.1,-1,-3, 0.1,-1,-3,-0.1,-1,3, 0.1,-1,3]

 while (plank <=5.0) :
  ri.Surface("wood",{"Ks":[0.1],"point c0":c0,"point c1":c1,"float grain":random.randint(2,20)})

ri = prman.Ri() # create an instance of the RenderMan interface
ri.Option("rib", {"string asciistyle": "indented"})



filename = "__render" #ShadowSpot.rib"
# this is the begining of the rib archive generation we can only
# make RI calls after this function else we get a core dump

# ArchiveRecord is used to add elements to the rib stream in this case comments
# note the function is overloaded so we can concatinate output
ri.ArchiveRecord(ri.COMMENT, 'File ' +filename)
ri.ArchiveRecord(ri.COMMENT, "Created by " + getpass.getuser())
ri.ArchiveRecord(ri.COMMENT, "Creation Date: " +time.ctime(time.time()))
ri.Declare(SpotName ,"string")

ri.Declare("Ambient" ,"string")
ri.Attribute("displacementbound",{ri.COORDINATESYSTEM:["world"],"uniform float sphere":[10.8]})

# now we add the display element using the usual elements
# FILENAME DISPLAY Type Output format
ri.Display("Teapot.png", "file", "rgb")
# Specify PAL resolution 1:1 pixel Aspect ratio
# now set the projection to perspective

# now we start our world

ri.LightSource ("ambientlight",{ri.HANDLEID: "Ambient","intensity" :[0.05]})

ri.LightSource( "shadowspot", {ri.HANDLEID:SpotName,
    "point from" : SpotFrom,
             "point to" : SpotTo,
             "float intensity" : [30],
             "string shadowname" :SpotName+".shad",
             "float coneangle" : coneAngle,
             "float conedeltaangle" : [0.05]})

ri.LightSource( "shadowspot", {ri.HANDLEID:Spot2Name,
    "point from" : Spot2From,
             "point to" : Spot2To,
             "float intensity" : [30],
             "string shadowname" :Spot2Name+".shad",
             "float coneangle" : coneAngle2,
             "float conedeltaangle" : [0.05]})



# and finally end the rib file