nvtristrip-ruby 0.5.0

data/README

@@ -0,0 +1,50 @@
+
+
+= NvTriStrip: Triangle stripification library
+
+NvTriStrip provides a Ruby interface for Nvidia's Triangle stripification
+library.
+
+Original NvTriStrip is available from http://developer.nvidia.com ,
+I've slightly modified the lib to fix compiling on various platforms.
+
+== Features
+
+All features and shortcomings of Nvidia's library are (hopefully) preserved.
+
+Namely, features
+* Makes trianglestrips out of triangle lists
+* Optimizes trianglestrips for good cache use
+* Optionally stitches separate strips with degenerates
+* Can throw small strips into a list instead
+* Remaps indices to improve spatial locality in your vertex buffer
+
+Some shortcomings
+* Limited geometry to 65k vertices (But that also has some practical value)
+* Uses global state to control some options (but should be otherwise reentrant)
+* Ruby version has to do some back and forth copying of the indices
+
+== Installation
+
+With rubygems:
+  gem install nvtristrip-ruby
+
+Otherwise:
+  ruby setup.rb
+
+== Usage
+
+  require 'nvtristrip'
+  
+  my_triangle_indices=[0,1,2,1,2,3] # Two triangles
+  validate=true
+
+  stripified_indices=NvTriStrip::generate_strips my_triangle_indices, validate
+  
+  # And now stripifiedIndices is an Array of NvTriStrip::PrimitiveGroup objects, which are Enumerable.
+
+  remapped_indices=NvTriStrip::remap_indices stripified_indices, 3
+
+  # And now remappedIndices is an array of PrimitiveGroups objects with indices
+  # remapped for better spatial locality. With this information you should remap your vertex buffer.
+

data/README.nvtristrip

@@ -0,0 +1,32 @@
+README for NvTriStrip, library version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use: 
+-#include "NvTriStrip.h"
+-put nvtristrip.lib in your library path (the pragma in nvtristrip.h will automatically look for the library).
+
+Check out NvTriStrip.h for the interface.
+
+See the StripTest source code (in function LoadXFileStripped) for an example of using the library.
+
+Features:
+-generates strips from arbitrary geometry.
+-flexibly optimizes for post TnL vertex caches (16 on GeForce1/2, 24 on GeForce3).
+-can stitch together strips using degenerate triangles, or not.
+-can output lists instead of strips.
+-can optionally throw excessively small strips into a list instead.
+-can remap indices to improve spatial locality in your vertex buffers.
+
+On cache sizes:
+Note that it's better to UNDERESTIMATE the cache size instead of OVERESTIMATING.
+So, if you're targetting GeForce1, 2, and 3, be conservative and use the GeForce1_2 cache 
+size, NOT the GeForce3 cache size.
+This will make sure you don't "blow" the cache of the GeForce1 and 2.
+Also note that the cache size you specify is the "actual" cache size, not the "effective"
+cache size you may have heard about.  This is 16 for GeForce1 and 2, and 24 for GeForce3.
+
+Credit goes to Curtis Beeson and Joe Demers for the basis for this stripifier and to Jason Regier and 
+Jon Stone at Blizzard for providing a much cleaner version of CreateStrips().
+
+Questions/comments email cem@nvidia.com
+

data/Rakefile

@@ -0,0 +1,76 @@
+
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+PKG_VERSION="0.5.0"
+
+file "ext/Makefile" => [ "ext/extconf.rb"] do
+  Dir.chdir "ext" do
+    ruby "extconf.rb"
+  end
+end
+
+EXT_SO="ext/nvtristrip.#{Config::CONFIG['DLEXT']}"
+
+file EXT_SO => FileList[
+    "ext/*.cpp",
+    "ext/*.h",
+    "ext/Makefile",
+  ] do
+  
+  Dir.chdir "ext" do
+    sh "make"
+  end
+  cp EXT_SO, "lib"
+  
+end
+
+task :default => :build
+
+desc "Build the extension"
+task :build => [EXT_SO]
+
+
+spec=Gem::Specification.new do |s|
+    s.name="nvtristrip-ruby"
+    s.author="Mikko Lehtonen"
+    s.version=PKG_VERSION
+    s.summary="Interface for NvTriStrip triangle stripification library."
+    s.platform=Gem::Platform::RUBY
+    s.has_rdoc=true
+    s.extra_rdoc_files = ["README","TODO","ext/RbTriStrip.cpp"]
+    s.files=Dir.glob("{test,lib}/**/*")+
+            Dir.glob("ext/**/*.{cpp,h,rb}")+
+            ["Rakefile","setup.rb","README.nvtristrip", "README"]
+
+    s.require_path="lib"
+    s.test_files=Dir.glob("test/test_*.rb")
+    s.extensions=FileList["ext/extconf.rb"].to_a
+    s.homepage="http://nvtristrip.rubyforge.org"
+    s.rubyforge_project="nvtristrip"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  
+end
+
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files=FileList['test/test*.rb']
+  t.verbose=true
+end
+
+Rake::RDocTask.new do |r|
+  r.rdoc_dir='doc/rdoc'
+#  r.options
+  r.rdoc_files.add ['README','TODO', 'ext/RbTriStrip.cpp']
+end
+
+
+CLEAN.include ['**/*.o', '**/*.log', "lib/"+File.basename(EXT_SO), EXT_SO]
+

data/TODO

@@ -0,0 +1,7 @@
+
+* Improve test-suite
+* Convenience function for remapping vertexbuffers?
+* Maybe try to modify nvtristrip lib to use the ruby arrays directly, so I wouldn't have to
+  copy the indices back and forth.
+* Clean up some of the code and improve documentation
+* Win32 precompiled gem

data/ext/NvTriStrip.cpp

@@ -0,0 +1,501 @@
+
+#include "NvTriStripObjects.h"
+#include "NvTriStrip.h"
+
+////////////////////////////////////////////////////////////////////////////////////////
+//private data
+static unsigned int cacheSize    = CACHESIZE_GEFORCE1_2;
+static bool bStitchStrips         = true;
+static unsigned int minStripSize = 0;
+static bool bListsOnly            = false;
+static unsigned int restartVal   = 0;
+static bool bRestart              = false;
+
+void EnableRestart(const unsigned int _restartVal)
+{
+	bRestart = true;
+	restartVal = _restartVal;
+}
+
+void DisableRestart()
+{
+	bRestart = false;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////
+// SetListsOnly()
+//
+// If set to true, will return an optimized list, with no strips at all.
+//
+// Default value: false
+//
+void SetListsOnly(const bool _bListsOnly)
+{
+	bListsOnly = _bListsOnly;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////
+// SetCacheSize()
+//
+// Sets the cache size which the stripfier uses to optimize the data.
+// Controls the length of the generated individual strips.
+// This is the "actual" cache size, so 24 for GeForce3 and 16 for GeForce1/2
+// You may want to play around with this number to tweak performance.
+//
+// Default value: 16
+//
+void SetCacheSize(const unsigned int _cacheSize)
+{
+	cacheSize = _cacheSize;
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////
+// SetStitchStrips()
+//
+// bool to indicate whether to stitch together strips into one huge strip or not.
+// If set to true, you'll get back one huge strip stitched together using degenerate
+//  triangles.
+// If set to false, you'll get back a large number of separate strips.
+//
+// Default value: true
+//
+void SetStitchStrips(const bool _bStitchStrips)
+{
+	bStitchStrips = _bStitchStrips;
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////
+// SetMinStripSize()
+//
+// Sets the minimum acceptable size for a strip, in triangles.
+// All strips generated which are shorter than this will be thrown into one big, separate list.
+//
+// Default value: 0
+//
+void SetMinStripSize(const unsigned int _minStripSize)
+{
+	minStripSize = _minStripSize;
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////
+//Cleanup strips / faces, used by generatestrips
+void Cleanup(NvStripInfoVec& tempStrips, NvFaceInfoVec& tempFaces)
+{
+	//delete strips
+	int i;
+	for(i = 0; i < tempStrips.size(); i++)
+	{
+		for(int j = 0; j < tempStrips[i]->m_faces.size(); j++)
+		{
+			delete tempStrips[i]->m_faces[j];
+			tempStrips[i]->m_faces[j] = NULL;
+		}
+		tempStrips[i]->m_faces.resize(0);
+		delete tempStrips[i];
+		tempStrips[i] = NULL;
+	}
+
+	//delete faces
+	for(i = 0; i < tempFaces.size(); i++)
+	{
+		delete tempFaces[i];
+		tempFaces[i] = NULL;
+	}
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////
+//SameTriangle()
+//
+//Returns true if the two triangles defined by firstTri and secondTri are the same
+// The "same" is defined in this case as having the same indices with the same winding order
+//
+bool SameTriangle(unsigned short firstTri0, unsigned short firstTri1, unsigned short firstTri2, 
+				  unsigned short secondTri0, unsigned short secondTri1, unsigned short secondTri2)
+{
+	bool isSame = false;
+
+	if (firstTri0 == secondTri0)
+	{
+		if (firstTri1 == secondTri1)
+		{
+			if (firstTri2 == secondTri2)
+				isSame = true;
+		}
+	}
+	else if (firstTri0 == secondTri1)
+	{
+		if (firstTri1 == secondTri2)
+		{
+			if (firstTri2 == secondTri0)
+				isSame = true;
+		}
+	}
+	else if (firstTri0 == secondTri2)
+	{
+		if (firstTri1 == secondTri0)
+		{
+			if (firstTri2 == secondTri1)
+				isSame = true;
+		}
+	}
+
+	return isSame;
+}
+
+
+bool TestTriangle(const unsigned short v0, const unsigned short v1, const unsigned short v2, const std::vector<NvFaceInfo>* in_bins, const int NUMBINS)
+{
+	//hash this triangle
+	bool isLegit = false;
+	int ctr = v0 % NUMBINS;
+	for (int k = 0; k < in_bins[ctr].size(); ++k)
+	{
+		//check triangles in this bin
+		if (SameTriangle(in_bins[ctr][k].m_v0, in_bins[ctr][k].m_v1, in_bins[ctr][k].m_v2, 
+			v0, v1, v2))
+		{
+			isLegit = true;
+			break;
+		}
+	}
+	if (!isLegit)
+	{
+		ctr = v1 % NUMBINS;
+		for (int k = 0; k < in_bins[ctr].size(); ++k)
+		{
+			//check triangles in this bin
+			if (SameTriangle(in_bins[ctr][k].m_v0, in_bins[ctr][k].m_v1, in_bins[ctr][k].m_v2, 
+				v0, v1, v2))
+			{
+				isLegit = true;
+				break;
+			}
+		}
+		
+		if (!isLegit)
+		{
+			ctr = v2 % NUMBINS;
+			for (int k = 0; k < in_bins[ctr].size(); ++k)
+			{
+				//check triangles in this bin
+				if (SameTriangle(in_bins[ctr][k].m_v0, in_bins[ctr][k].m_v1, in_bins[ctr][k].m_v2, 
+					v0, v1, v2))
+				{
+					isLegit = true;
+					break;
+				}
+			}
+			
+		}
+	}
+
+	return isLegit;
+}
+	
+
+////////////////////////////////////////////////////////////////////////////////////////
+// GenerateStrips()
+//
+// in_indices: input index list, the indices you would use to render
+// in_numIndices: number of entries in in_indices
+// primGroups: array of optimized/stripified PrimitiveGroups
+// numGroups: number of groups returned
+//
+// Be sure to call delete[] on the returned primGroups to avoid leaking mem
+//
+bool GenerateStrips(const unsigned short* in_indices, const unsigned int in_numIndices,
+					PrimitiveGroup** primGroups, unsigned short* numGroups, bool validateEnabled)
+{
+	//put data in format that the stripifier likes
+	WordVec tempIndices;
+	tempIndices.resize(in_numIndices);
+	unsigned short maxIndex = 0;
+	unsigned short minIndex = 0xFFFF;
+	for(int i = 0; i < in_numIndices; i++)
+	{
+		tempIndices[i] = in_indices[i];
+		if (in_indices[i] > maxIndex)
+			maxIndex = in_indices[i];
+		if (in_indices[i] < minIndex)
+			minIndex = in_indices[i];
+	}
+	NvStripInfoVec tempStrips;
+	NvFaceInfoVec tempFaces;
+
+	NvStripifier stripifier;
+	
+	//do actual stripification
+	stripifier.Stripify(tempIndices, cacheSize, minStripSize, maxIndex, tempStrips, tempFaces);
+
+	//stitch strips together
+	IntVec stripIndices;
+	unsigned int numSeparateStrips = 0;
+
+	if(bListsOnly)
+	{
+		//if we're outputting only lists, we're done
+		*numGroups = 1;
+		(*primGroups) = new PrimitiveGroup[*numGroups];
+		PrimitiveGroup* primGroupArray = *primGroups;
+
+		//count the total number of indices
+		unsigned int numIndices = 0;
+		int i;
+		for(i = 0; i < tempStrips.size(); i++)
+		{
+			numIndices += tempStrips[i]->m_faces.size() * 3;
+		}
+
+		//add in the list
+		numIndices += tempFaces.size() * 3;
+
+		primGroupArray[0].type       = PT_LIST;
+		primGroupArray[0].numIndices = numIndices;
+		primGroupArray[0].indices    = new unsigned short[numIndices];
+
+		//do strips
+		unsigned int indexCtr = 0;
+		for(i = 0; i < tempStrips.size(); i++)
+		{
+			for(int j = 0; j < tempStrips[i]->m_faces.size(); j++)
+			{
+				//degenerates are of no use with lists
+				if(!NvStripifier::IsDegenerate(tempStrips[i]->m_faces[j]))
+				{
+					primGroupArray[0].indices[indexCtr++] = tempStrips[i]->m_faces[j]->m_v0;
+					primGroupArray[0].indices[indexCtr++] = tempStrips[i]->m_faces[j]->m_v1;
+					primGroupArray[0].indices[indexCtr++] = tempStrips[i]->m_faces[j]->m_v2;
+				}
+				else
+				{
+					//we've removed a tri, reduce the number of indices
+					primGroupArray[0].numIndices -= 3;
+				}
+			}
+		}
+
+		//do lists
+		for(i = 0; i < tempFaces.size(); i++)
+		{			
+			primGroupArray[0].indices[indexCtr++] = tempFaces[i]->m_v0;
+			primGroupArray[0].indices[indexCtr++] = tempFaces[i]->m_v1;
+			primGroupArray[0].indices[indexCtr++] = tempFaces[i]->m_v2;
+		}
+	}
+	else
+	{
+		stripifier.CreateStrips(tempStrips, stripIndices, bStitchStrips, numSeparateStrips, bRestart, restartVal);
+
+		//if we're stitching strips together, we better get back only one strip from CreateStrips()
+		assert( (bStitchStrips && (numSeparateStrips == 1)) || !bStitchStrips);
+		
+		//convert to output format
+		*numGroups = numSeparateStrips; //for the strips
+		if(tempFaces.size() != 0)
+			(*numGroups)++;  //we've got a list as well, increment
+		(*primGroups) = new PrimitiveGroup[*numGroups];
+		
+		PrimitiveGroup* primGroupArray = *primGroups;
+		
+		//first, the strips
+		int startingLoc = 0;
+		for(int stripCtr = 0; stripCtr < numSeparateStrips; stripCtr++)
+		{
+			int stripLength = 0;
+
+			if(!bStitchStrips)
+			{
+				//if we've got multiple strips, we need to figure out the correct length
+				int i;
+				for(i = startingLoc; i < stripIndices.size(); i++)
+				{
+					if(stripIndices[i] == -1)
+						break;
+				}
+				
+				stripLength = i - startingLoc;
+			}
+			else
+				stripLength = stripIndices.size();
+			
+			primGroupArray[stripCtr].type       = PT_STRIP;
+			primGroupArray[stripCtr].indices    = new unsigned short[stripLength];
+			primGroupArray[stripCtr].numIndices = stripLength;
+			
+			int indexCtr = 0;
+			for(int i = startingLoc; i < stripLength + startingLoc; i++)
+				primGroupArray[stripCtr].indices[indexCtr++] = stripIndices[i];
+
+			//we add 1 to account for the -1 separating strips
+			//this doesn't break the stitched case since we'll exit the loop
+			startingLoc += stripLength + 1; 
+		}
+		
+		//next, the list
+		if(tempFaces.size() != 0)
+		{
+			int faceGroupLoc = (*numGroups) - 1;    //the face group is the last one
+			primGroupArray[faceGroupLoc].type       = PT_LIST;
+			primGroupArray[faceGroupLoc].indices    = new unsigned short[tempFaces.size() * 3];
+			primGroupArray[faceGroupLoc].numIndices = tempFaces.size() * 3;
+			int indexCtr = 0;
+			for(int i = 0; i < tempFaces.size(); i++)
+			{
+				primGroupArray[faceGroupLoc].indices[indexCtr++] = tempFaces[i]->m_v0;
+				primGroupArray[faceGroupLoc].indices[indexCtr++] = tempFaces[i]->m_v1;
+				primGroupArray[faceGroupLoc].indices[indexCtr++] = tempFaces[i]->m_v2;
+			}
+		}
+	}
+
+	//validate generated data against input
+	if (validateEnabled)
+	{
+		const int NUMBINS = 100;
+
+		std::vector<NvFaceInfo> in_bins[NUMBINS];
+		
+		int i;
+		//hash input indices on first index
+		for (i = 0; i < in_numIndices; i += 3)
+		{
+			NvFaceInfo faceInfo(in_indices[i], in_indices[i + 1], in_indices[i + 2]);
+			in_bins[in_indices[i] % NUMBINS].push_back(faceInfo);
+		}
+		
+		for (i = 0; i < *numGroups; ++i)
+		{
+			switch ((*primGroups)[i].type)
+			{
+				case PT_LIST:
+				{
+					for (int j = 0; j < (*primGroups)[i].numIndices; j += 3)
+					{
+						unsigned short v0 = (*primGroups)[i].indices[j];
+						unsigned short v1 = (*primGroups)[i].indices[j + 1];
+						unsigned short v2 = (*primGroups)[i].indices[j + 2];
+						
+						//ignore degenerates
+						if (NvStripifier::IsDegenerate(v0, v1, v2))
+							continue;
+
+						if (!TestTriangle(v0, v1, v2, in_bins, NUMBINS))
+						{
+							Cleanup(tempStrips, tempFaces);
+							return false;
+						}
+					}
+					break;
+				}
+
+				case PT_STRIP:
+				{
+					int brokenCtr = 0;
+					bool flip = false;
+					for (int j = 2; j < (*primGroups)[i].numIndices; ++j)
+					{
+						unsigned short v0 = (*primGroups)[i].indices[j - 2];
+						unsigned short v1 = (*primGroups)[i].indices[j - 1];
+						unsigned short v2 = (*primGroups)[i].indices[j];
+						
+						if (flip)
+						{
+							//swap v1 and v2
+							unsigned short swap = v1;
+							v1 = v2;
+							v2 = swap;
+						}
+
+						//ignore degenerates
+						if (NvStripifier::IsDegenerate(v0, v1, v2))
+						{
+							flip = !flip;
+							continue;
+						}
+
+						if (!TestTriangle(v0, v1, v2, in_bins, NUMBINS))
+						{
+							Cleanup(tempStrips, tempFaces);
+							return false;
+						}
+
+						flip = !flip;
+					}
+					break;
+				}
+
+				case PT_FAN:
+				default:
+					break;
+			}
+		}
+
+	}
+
+	//clean up everything
+	Cleanup(tempStrips, tempFaces);
+
+	return true;
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////
+// RemapIndices()
+//
+// Function to remap your indices to improve spatial locality in your vertex buffer.
+//
+// in_primGroups: array of PrimitiveGroups you want remapped
+// numGroups: number of entries in in_primGroups
+// numVerts: number of vertices in your vertex buffer, also can be thought of as the range
+//  of acceptable values for indices in your primitive groups.
+// remappedGroups: array of remapped PrimitiveGroups
+//
+// Note that, according to the remapping handed back to you, you must reorder your 
+//  vertex buffer.
+//
+void RemapIndices(const PrimitiveGroup* in_primGroups, const unsigned short numGroups,
+				  const unsigned short numVerts, PrimitiveGroup** remappedGroups)
+{
+	(*remappedGroups) = new PrimitiveGroup[numGroups];
+
+	//caches oldIndex --> newIndex conversion
+	int *indexCache;
+	indexCache = new int[numVerts];
+	memset(indexCache, -1, sizeof(int)*numVerts);
+	
+	//loop over primitive groups
+	unsigned int indexCtr = 0;
+	for(int i = 0; i < numGroups; i++)
+	{
+		unsigned int numIndices = in_primGroups[i].numIndices;
+
+		//init remapped group
+		(*remappedGroups)[i].type       = in_primGroups[i].type;
+		(*remappedGroups)[i].numIndices = numIndices;
+		(*remappedGroups)[i].indices    = new unsigned short[numIndices];
+
+		for(int j = 0; j < numIndices; j++)
+		{
+			int cachedIndex = indexCache[in_primGroups[i].indices[j]];
+			if(cachedIndex == -1) //we haven't seen this index before
+			{
+				//point to "last" vertex in VB
+				(*remappedGroups)[i].indices[j] = indexCtr;
+
+				//add to index cache, increment
+				indexCache[in_primGroups[i].indices[j]] = indexCtr++;
+			}
+			else
+			{
+				//we've seen this index before
+				(*remappedGroups)[i].indices[j] = cachedIndex;
+			}
+		}
+	}
+
+	delete[] indexCache;
+}