1. The Vertex

A Vertex (pl. Vertices) specifies a number of Attributes associated with a single Point in space. In the fixed-function environment a Vertex commonly includes Position, Normal, Color and/or Texture Coordinates. The only Attribute that is not optional an must be specified is the Vertex's Position, usually consisting of 3 float.
In Shader Program driven rendering it is also possible to specify custom Vertex Attributes which are previously unknown to OpenGL, such as Radius or Bone Index and Weight for Skeletal Animation. For the sake of simplicity we'll re-create one of the Vertex formats OpenGL already knows, namely InterleavedArrayFormat.T2fN3fV3f. This format contains 2 float for Texture Coordinates, 3 float for the Normal direction and 3 float to specify the Position.

Thanks to the included Math-Library in OpenTK, we're allowed to specify an arbitrary Vertex struct for our requirements, which is much more elegant to handle than a float[] array.

This leads to a Vertex consisting of 8 float, or 32 byte. We can now declare an Array of Vertices to describe multiple Points and allow easy indexing/referencing them.

The Vertex-Array Vertices can now be created and filled with data. Addressing elements is as convenient as in the following example:

An Index is simply a byte, ushort or uint, referencing an element in the Vertices Array. So if we decide to draw a single Vertex 100 times at the same spot, instead of storing 100 times the same Vertex in Vertices, we can reference it 100 times from the Indices Array:

Basically the Indices Array is used to describe the primitives and the Vertex Array is used to declare the corner points.

We can also use collections to store our Vertices, but it's recommended you stick with a simple Array to make sure your Indices are valid at all times.
Now the Vertices and Indices Arrays can be used to describe the edges of any Geometric Pritimitve Type.

Once the Arrays are filled with data it can be drawn in Immediate Mode, as Vertex Array or sent into a Vertex Buffer Object.

2. Geometric Primitive Types

OpenGL requires you to specify the Geometric Primitive Type of the Vertices you wish to draw. This is usually expected when you begin drawing in either Immediate Mode (GL.Begin), GL.DrawArrays or GL.DrawElements.

Fig. 1: In the above graphic all valid Geometric Primitive Types are shown, their winding is Clockwise (irrelevant for Points and Lines).

This is important, because drawing a set of Vertices as Triangles, which are internally set up to be used with Quads, will result only in garbage being displayed.
Examine Figure 1, you will see that v3 in a Quad is used to finish the shape, while Triangles uses v3 to start the next shape. The next drawn Triangle will be v3, v4, v5 which isn't something that belongs to any surface, if the Vertices were originally intended to be drawn as Quads.

However Points and Lines are an Exception here. You can draw every other Geometric Primitive Type as Points, in order to visualize the Vertices of the Object. Some more possibilities are:

• QuadStrip, TriangleStrip and LineStrip can be interchanged, if the source data isn't a LineStrip.
• Quads can be drawn as Lines with the restriction that there are no lines between v1, v2 and v3, v0.
• Polygon can be drawn as LineLoop
• TriangleFan can be drawn as Polygon or LineLoop

The smallest common denominator for all filled surfaces (i.e. no Points or Lines) is the Triangle. This Geometric Primitive Type has the special attribute of always being planar and is currently the best way to describe a 3D Object to GPU hardware.
While OpenGL allows to draw Quads or Polygons aswell, it is quite easy to run into lighting problems if the surface is not perfectly planar. Internally, OpenGL breaks Quads and Polygons into Triangles, in order to rasterize them.

1. Points
   Specifies 1 Point per Vertex v, thus this is usually only used with GL.DrawArrays().
   n Points = Vertex * (1n);
2. Lines
   Two Vertices form a Line.
   n Lines = Vertex * (2n);
3. LineStrip
   The first Vertex issued begins the LineStrip, every consecutive issued Vertex marks a joint in the Line.
   n Line Segments in the Strip = Vertex * (1+1n)
4. LineLoop
   Same as LineStrip, but the very first and last issued Vertex are automatically connected by an extra Line segment.
   n Line Segments in the Loop = Vertex * (1n);
5. Polygon
   Note that the first and the last Vertex will be connected automatically, just like LineLoop.
   Polygon with n Edges = Vertex * (1n);
   Note: This primitive type should really be avoided whenever possible, basically the Polygon will be split to Triangles in the end anyways. Like Quads, polygons must be planar or be displayed incorrectly. Another Problem is that there is only 1 single Polygon in a begin-end block, which leads to multiple draw calls when drawing a mesh, or using the Extensions GL.MultiDrawElements or GL.MultiDrawArrays.
6. Quads
   Quads are especially useful to work in 2D with bitmap Images, since those are typically rectangular aswell. Care has to be taken that the surface is planar, otherwise the split into Triangles will become visible.
   n Quads = Vertex * (4n);
7. QuadStrip
   Like the Triangle-strip, the QuadStrip is a more compact representation of a sequence of connected Quads.
   n Quads in Quadstrip = Vertex * (2+2n);
8. Triangles
   This way to represent a mesh offers the most control over how the Triangles are sorted, a Triangle always consists of 3 Vertex.
   n Triangles = Vertex * (3n);
   Note: It might look like an inefficient brute force approach at first, but it has it's advantages over TriangleStrip. Most of all, since you are not required to supply Triangles in sequenced strips, it is possible to arrange Triangles in a way that makes good use of the Vertex Caches. If the Triangle you currently want to draw shares an edge with one of the Triangles that have been recently drawn, you get 2 Vertices, that are stored in the Vertex Cache, almost for free. This is basically the same what stripification does, but you are not restricted to a certain Direction and forced to insert degenerated Triangles.
9. TriangleStrip
   The idea behind this way of drawing is that if you want to represent a solid and closed Object, most neighbour Triangles will share 2 Vertices (an edge). You start by defining the initial Triangle (3 Vertices) and after that every new Triangle will only require a single new Vertex for a new Triangle.
   n Triangles in Strip = Vertex * (2+1n);
   Note: While this primitive type is very useful for storing huge meshes (2+1n Vertices per strip as opposed to 3n for BeginMode.Triangles), the big disadvantage of TriangleStrip is that there is no command to tell OpenGL that you wish to start a new strip while inside the glBegin/glEnd block. Ofcourse you can glEnd(); and start a new strip, but that costs API calls. A workaround to avoid exiting the begin/end block is to create 2 or more degenerate Triangles (you can imagine them as Lines) at the end of a strip and then start the next one, but this also comes at the cost of processing Triangles that will inevitably be culled and aren't visible. Especially when optimizing an Object to be in a Vertex Cache friendly layout, it is essential to start new strips in order to reuse Vertices from previous draws.
10. TriangleFan
    A fan is defined by a center Vertex, which will be reused for all Triangles in the Fan, followed by border Vertices. It is very useful to represent convex n-gons consisting of more than 4 vertices and disc shapes, like the caps of a cylinder.

When looking at the graphic, Triangle- and Quad-strips might look quite appealing due to their low memory usage. They are beneficial for certain tasks, but Triangles are the best primitive type to represent an arbitrary mesh, because it's not restricting locality and allows further optimizations. It's just not realistic that you can have all your 3D Objects in Quads and OpenGL will split them internally into Triangles anyway. 3 ushort per Triangle isn't much memory, and still allows to index 64k unique Vertex in a mesh, the number of Triangles can be much higher. Don't hardwire BeginMode.Triangles into your programs though, for example Quads are very commonly used in orthographic drawing of UI Elements such as Buttons, Text or Sprites.

Should TriangleStrip get an core/ARB command to start a new strip within the begin/end block (only nVidia driver has such an Extension to restart the primitive) this might change, but currently the smaller data structure of the strip does not make up for the performance gains a Triangle List gets from Vertex Cache optimization. Ofcourse you can experiment with the GL.MultiDraw Extension mentioned above, but using it will break using other Extensions such as DirectX 10 instancing.

3.a Vertex Buffer Objects

Introduction
The advantage of VBO (Vertex Buffer Objects) is that we can tell OpenGL to store information used for drawing - like Position, Colors, Texture Coordinates and Normals - directly in the Video-card's Memory, rather than storing it in System Memory and pass it to the graphics Hardware every time we wish to draw it. While this has been already doable with Display Lists before, VBO has the advantage that we're able to retrieve a Pointer to the data in Video Memory and read/write directly to it, if necessary. This can be a huge performance boost for dynamic meshes and is for years the best overall solution for storing - both, static and dynamic - Meshes.

Creation
Handling VBOs is very similar to handling Texture objects, we can generate/delete handles, bind them or fill them with data. For this tutorial we will need 2 objects, one VBO containing all Vertex information (Texture, Normal and Position in this example case) and an IBO (Index Buffer Object) referencing Vertices from the VBO to form Triangles. This has the advantage that, when we have uploaded the data to the VBO/IBO later on, we can draw the whole mesh with a single GL.DrawElements call.

First we acquire two Objects to use:

Although it is unlikely, OpenGL could complain that it ran out of memory or that the extension is not supported, it should be checked with GL.GetError. If everything went smooth we have 2 objects to work with available now.

Delete
The OpenGL driver should clean up all our mess when it deletes the render context, it's always a good idea to clean up on your own where you can. We remove the objects we reserved at the buffer creation by calling:

Binding
To select which object you currently want to work with, simply bind the handle to either BufferTarget.ArrayBuffer or BufferTarget.ElementArrayBuffer. The first is used to store position, uv, normals, etc. (named VBO) and the later is pointing at those vertices to define geometry (named IBO).

It is not required to bind a buffer to both targets, for example you could store only the vertices in the VBO and keep the indices in system memory. Also, the two objects are not tied together in any way, for example you could build different triangle lists for BufferTarget.ElementArrayBuffer to implement LOD on the same set of vertices, simply by binding the desired element array.

Theres two important things to keep in mind though:

1) While working with VBOs, GL.EnableClientState(EnableCap.VertexArray); must be enabled. if using Normals, GL.EnableClientState(EnableCap.NormalArray), just like classic Vertex Arrays.

2) All Vertex Array related commands will be used on the currently bound objects until you explicitly bind zero '0' to disable hardware VBO.

Passing Data
There are several ways to fill the object's data, we will focus on using GL.BufferData and directly writing to video memory. The third option would be GL.BufferSubData which is quite straightforward to use once you are familiar with GL.BufferData.

1. GL.BufferData
   We will start by preparing the IBO, it would not make a difference if we set up the VBO first, we simply start with the shorter one.

   We make sure the correct object is bound (it is not required to do this, if the buffer is already bound. Just here to clarify on which object we currently work on)
   

   GL.BindBuffer( BufferTarget.ElementArrayBuffer, VBOid[ 1 ] );
   
   In the example application ushort has been used for Indices, because 16 Bits [0..65535] are more available Vertices than used by most real-time rendered meshes, however the mesh could index way more Vertices using a type like uint. Using ushort, OpenGL will store this data as 2 Bytes per index, saving memory compared to a 4 Bytes UInt32 per index.

   The function GL.BufferData's first parameter is the target we want to use, the second is the amount of memory (in bytes) we need allocated to hold all our data. The third parameter is pointing at the data we wish to send to the graphics card, this can be IntPtr.Zero and you may send the data at a later stage with GL.MapBuffer (more about this later). The last parameter is an optimization hint for the driver, it will place your data in the best suited place for your purposes.
   

   GL.BufferData( BufferTarget.ElementArrayBuffer, (IntPtr) ( Indices.Length * sizeof( ushort ) ), Indices, BufferUsageHint.StaticDraw );
   
   That's all, OpenGL now has a copy of Indices available and we could dispose the array, assuming we have the Index Count of the array stored in a variable for the draw call later on.

   Now that we've stored the indices in an IBO, the Vertices are next. Again, we make sure the binding is correct, give a pointer to the Vertex count, and finally the usage hint.
   

   GL.BindBuffer( BufferTarget.ArrayBuffer, VBOid[ 0 ] );
   GL.BufferData( BufferTarget.ArrayBuffer, (IntPtr) ( Vertices.Length * 8 * sizeof( float ) ), Vertices, BufferUsageHint.StaticDraw );

   There's a table at the bottom of this page, explaining the options in the enum BufferUsageHint in more detail.

2. GL.MapBuffer / GL.UnmapBuffer

   While the first described technique to pass data into the objects required a copy of the data in system memory, this alternative will give us a pointer to the video memory reserved by the object. This is useful for dynamic models that have no copy in client memory that could be used by GL.BufferData, since you wish to rebuild it every single frame (e.g. fully procedural objects, particle system).

   First we make sure that we got the desired object bound and reserve memory, the pointer towards the Indices is actually IntPtr.Zero, because we only need an empty buffer.
   

   GL.BindBuffer( BufferTarget.ElementArrayBuffer, VBOid[ 0 ] );
   GL.BufferData( BufferTarget.ElementArrayBuffer, (IntPtr) ( Indices.Length * sizeof( ushort ) ), IntPtr.Zero, BufferUsageHint.StaticDraw );

   Note that you should change BufferUsageHint.StaticDraw properly according to what you intend to do with the Data, there's a table at the bottom of this page. Now we're able to request a pointer to the video memory.

   IntPtr VideoMemoryIntPtr = GL.MapBuffer(BufferTarget.ElementArrayBuffer, BufferAccess.WriteOnly);

   Valid access flags for the pointer are BufferAccess.ReadOnly, BufferAccess.WriteOnly or BufferAccess.ReadWrite, which help the driver understand what you're going to do with the data. Note that the data's object is locked until we unmap it, so we want to keep the timespan over which we use the pointer as short as possible. We may now write some data into the buffer, once we're done we must release the lock.
   

   unsafe
   {
     fixed ( ushort* SystemMemory = &Indices[0] )
     {
       ushort* VideoMemory = (ushort*) VideoMemoryIntPtr.ToPointer();
       for ( int i = 0; i < Indices.Length; i++ )
         VideoMemory[ i ] = SystemMemory[ i ]; // simulate what GL.BufferData would do
     }
   }
   GL.UnmapBuffer( BufferTarget.ElementArrayBuffer );
   
   The pointer is now invalid and may not be stored for future use, if we wish to modify the object again, we have to call GL.MapBuffer again.

Further reading
Visit this link in order to tell OpenGL about the composition of your Vertex data, and this link for drawing the data.

Optimization:

One hint from the nVidia whitepaper was regarding the situation, if we want to update all data in the buffer object by using GL.MapBuffer and not retrieve any of the old data. Although this is a bad idea, because mapping the buffer is a more expensive operation than just calling GL.BufferData, it might be necessary in cases where you have no copy of the data in system memory, but build it on the fly. The solution to making this somewhat efficient is first calling GL.BufferData with a IntPtr.Zero again, which tells the driver that the old data isn't valid anymore. Calling GL.MapBuffer will return a new pointer to a valid memory location of the requested size to write to, while the old data will be cleaned up once it's not used in any draw operations anymore.

Also note that either reading from a VBO or wrapping it into a Display List is very slow and should both be avoided.

Table 1:
BufferUsageHint.Static... Assumed to be a 1-to-n update-to-draw. Means the data is specified once (during initialization).
BufferUsageHint.Dynamic... Assumed to be a n-to-n update-to-draw. Means the data is drawn multiple times before it changes.
BufferUsageHint.Stream... Assumed to be a 1-to-1 update-to-draw. Means the data is very volatile and will change every frame.

...Draw Means the buffer will be used to sending data to GPU. video memory (Static|StreamDraw) or AGP (DynamicDraw)
...Read Means the data must be easy to access, will most likely be system or AGP memory.
...Copy Means we are about to do some ..Read and ..Draw operations.

3.b Attribute Offsets and Strides

Setting Strides and Offsets for Vertex Arrays and VBO

There are 2 ways to tell OpenGL in which layout the Vertices are stored:

1. GL.InterleavedArrays()
   What GL.InterleavedArrays does is enable/disable the required client states for OpenGL to interpret our passed data, the first parameter tells that we have 2 floats for Texture Coordinates (T2f), 3 floats for Normal (N3F) and 3 floats for position (V3F). The second parameter is the stride that will be jumped to find the second, third, etc. set of texcoord/normal/position values. Since our Vertices are tighly packed, no stride (zero) is correct. The last parameter should point at Indices, but we already sent them to the VBO in video memory, no need to point at them again:
   
   GL.InterleavedArrays( InterleavedArrayFormat.T2fN3fV3f, 0, null );
   
   This command has the advantage that it's very obvious to the OpenGL driver what layout of data we have supplied, and it may be possible for the driver to optimize the memory. Remember that GL.InterleavedArrays will change states, if you manually disable EnableCap.VertexArray, EnableCap.NormalArray, EnableCap.TextureCoordArray or changing GL.VertexPointer, GL.NormalPointer or GL.TexCoordPointer (after calling GL.InterleavedArrays and before calling GL.DrawElements) make sure to enable them again or you won't see anything.
2. Setting the offsets/strides manually
   For the Vertex format InterleavedArrayFormat.T2fN3fV3f, the correct pointer setup is:
   
   GL.TexCoordPointer( 2, TexCoordPointerType.Float, 8 * sizeof( float ), (IntPtr) ( 0 ) );
   GL.NormalPointer( NormalPointerType.Float, 8 * sizeof( float ), (IntPtr) ( 2 * sizeof( float ) ) );
   GL.VertexPointer( 3, VertexPointerType.Float, 8 * sizeof( float ), (IntPtr) ( 5 * sizeof( float ) ) );
   1. The first parameter is the number of components to describe that attribute. For GL.NormalPointer this is always 3 components, but is variable for Texture coordinates and Position (and Color).
   2. The second parameter is the type of the components.
   3. The third parameter is the number of bytes between Texture coordinate 0, 1, 2, 3, etc. also known as stride.
   4. The last parameter indicates the byte offset of the first appearance of the attribute, this makes perfect sense if you recall the layout of our Vertex struct.

3.c Vertex Arrays

Although it's really not recommended using them (besides for compiling to a Display List), Vertex Arrays can be safely used like this:

pseudocode:

You must use the unsafe float* overloads for this to work, not the object overloads (which pin internally)

The important bit is that the pin between GL.*Pointer and GL.Draw* may not be released. For arrays smaller than 85000 Bytes it is also important to call GL.Finish in order for the CPU to wait until the GPU is done reading all pinned data. You might get away without the GL.Finish command for a very short VA or ones larger than 85000 Bytes, but once the pin is released the Garbage Collector is allowed to move or cleanup your array. This leads to difficult to trace access violations with medium sized VA (without waiting for OpenGL to finish processing it) and will randomly occur at frames where the GC kicks in.

GL.Finish will obviously kill performance, since you have a blocking statement executed, which forces CPU and GPU to work in sync and not taking advantage of parallel processing. That's why it's recommended to use Display Lists or Vertex Buffer Objects instead.

Please visit this discussion in the forum for more information.

4. Drawing

In order to tell OpenGL to draw primitives for us, there's basically two ways to go:

1. Immediate Mode, as in specifying every single Vertex manually.
2. Vertex Buffers (or Vertex Arrays), drawing a whole Mesh with a single Command.

In order for all GL.Draw*-Functions to output geometric Primitives, EnableCap.VertexArray must be enabled first.

1. Immediate Mode
   Hereby every single Vertex we wish to draw has to be issued manually.
   
   // GL.DrawArrays behaviour
   GL.Begin( BeginMode.Points );
   for ( uint i = 0; i < Vertices.Length; i++ )
   {
      GL.TexCoord2( Vertices[ i ].TexCoord );
      GL.Normal3( Vertices[ i ].Normal );
      GL.Vertex3( Vertices[ i ].Position );
   }
   GL.End( );
   
   // GL.DrawElements behaviour
   GL.Begin( BeginMode.Points );
   for ( uint i = 0; i < Indices.Length; i++ )
   {
      GL.TexCoord2( Vertices[ Indices[ i ] ].TexCoord );
      GL.Normal3( Vertices[ Indices[ i ] ].Normal );
      GL.Vertex3( Vertices[ Indices[ i ] ].Position );
   }
   GL.End( );
2. GL.DrawArrays( BeginMode, int First, int Length )
   This Command is used together with Vertex Arrays or Vertex Buffer Objects, see setting Attribute Pointers. This line will automatically draw all Vertex contained in Vertices in order of appearance in the Array.
   
   GL.DrawArrays( BeginMode.Points, 0, Vertices.Length );
3. GL.DrawElements( BeginMode, int Length, DrawElementsType, object )
   Like DrawArrays this Command is used together with Vertex Arrays or VBO. It uses an unsigned Array (byte, ushort, uint) to Index the Vertex Array. This is particularly useful for 3D Models where the Triangles describing the surface share Edges and Vertices.
   
   GL.DrawElements( BeginMode.TriangleStrip, Indices.Length, DrawElementsType.UnsignedInt, Indices );
4. GL.DrawRangeElements( BeginMode, int Start, int End, int Count, DrawElementsType, object )
   This function behaves largely like GL.DrawElements, with the change that you may specify a starting index rather than starting at 0.
   Start and End are the smallest and largest Array-Index into Indices. Count is the number of Elements to render.
   
   // behaviour equal to GL.DrawElements
   GL.DrawRangeElements( BeginMode.TriangleStrip, 0, Indices.Length-1, Indices.Length, DrawElementsType.UnsignedInt, Indices );
5. GL.DrawArraysInstanced( BeginMode, int First, int Length, int primcount )
   This function is only available on DX10 hardware and basically behaves like this:
   
   for (int gl_InstanceID=0; gl_InstanceID < primcount; gl_InstanceID++ )
      GL.DrawArrays( BeginMode, First, Length );
   
   gl_InstanceID is a uniform variable available to the Vertex Shader, which (in conjunction with GL.UniformMatrix) can be used to assign each Instance drawn it's own unique Orientation Matrix.
6. GL.DrawElementsInstanced( BeginMode, int Length, DrawElementsType, object, int primcount )
   This function is only available on DX10 hardware and internally unrolls into:
   
   for (int gl_InstanceID=0; gl_InstanceID < primcount; gl_InstanceID++ )
      GL.DrawElements( BeginMode, Length, DrawElementsType, Object );
   
   gl_InstanceID is a uniform variable available to the Vertex Shader, which (in conjunction with GL.UniformMatrix) can be used to assign each Instance drawn it's own unique orientation Matrix.

Extension References
http://www.opengl.org/registry/specs/EXT/draw_range_elements.txt
http://www.opengl.org/registry/specs/EXT/draw_instanced.txt
http://www.opengl.org/registry/specs/EXT/multi_draw_arrays.txt

4.b Drawing Optimizations

This page is just giving a starting point for optimizations, the links below provide more in-depth information.

• Make sure there are no OpenGL errors. Any error usually kills the framerate.
• Enable backface culling with GL.Enable(EnableCap.CullFace) rather than relying on the Z-Buffer.
• If you're drawing a scene that covers the whole screen each frame, only clear depth buffer but not the color buffer.
• Organize drawing in a way that requires as few state changes as possible. Don't enable states that are not needed.
• Use GL.Hint(...) wherever applicable.
• Avoid Immediate Mode or Vertex Arrays in favor of Display Lists or Vertex Buffer Objects.
• Use GL.DrawRangeElements instead of GL.DrawElements for a slight performance gain.
• Take advantage of S3TC Texture compression and Vertex Cache optimizing algorithms.

Links:

http://www.mesa3d.org/brianp/sig97/perfopt.htm
http://ati.amd.com/developer/SDK/AMD_SDK_Samples_May2007/Documentations/...
http://developer.nvidia.com/object/gpu_programming_guide.html
http://www.opengl.org/pipeline/article/vol003_8/
http://developer.apple.com/graphicsimaging/opengl/

Last edit of Links: March 2008

5. OpenTK.Utilities standard Objects and Model Loader

Placeholder

this page will contain whatever spawns off http://opentk.sourceforge.net/home/?q=node/58