ogre.rb 0.1-i686-linux

data/README

@@ -0,0 +1,79 @@
+= Ogre.rb : Ruby wrapper around Ogre 
+
+Welcome to Ogre.rb, the Ruby wrapper around the Ogre rendering engine. This currently is only
+known to build and run correctly on Linux, though I expect this will work just fine on Mac as well. 
+Windows support will come later.
+
+Ogre.rb is currently built for Ruby 1.8.5+ and Ogre 1.4.x (Eihort)
+
+== Usage
+
+Assuming Ogre.rb and OIS.rb are compiled, you are free to copy lib/ogre.so and lib/OIS.so into your project
+as needed. You will need to either place the extensions next to the Ogre and OIS libraries or have your
+environment set up to know where these libraries are located. Then, using Ogre.rb is as easy as:
+
+	require 'ogre'
+	require 'ruby_ois'
+
+and optionally
+
+	require 'navi' (note that navi is only supported in Windows using Direct3D at the moment)
+	
+The samples/ directory is a direct port of the Ogre sample programs. 
+
+== Contributing 
+
+Please post patches, feature requests, bug fixes to the rubyforge website at http://rubyforge.org/projects/ogrerb.
+As I'm not sure exactly how to unit test such a wrapper, it will be greatly appreciated if changes are proven as
+part of a sample application.
+
+== Build Requirements 
+
+   * rake
+   * Ogre 1.4.x (Eihort)
+   * OIS
+   * swig 1.3.31+ (uses -autorename)
+   * pkg-config (Linux) 
+
+== Build Steps 
+
+=== Linux 
+
+rake build_all
+
+The resulting files can be found in ogrerb/lib.
+
+=== Mac
+
+TODO
+
+=== Windows 
+
+==== Setup your environment
+
+1. Install Ruby One-Click Installer: http://rubyforge.org/projects/rubyinstaller/
+1. Install Visual Studio Express 2005: http://msdn.microsoft.com/vstudio/express/ (Be sure to register environment variables)
+1. You'll need to remove the following 3 lines of the [ruby install dir]/lib/ruby/1.8/i386-mswin32/config.h file:
+	#if _MSC_VER != 1200
+	#error MSC version unmatch
+	#endif
+1. You need the MS platform SDK available here(ish): http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en. 
+1. Be sure to register environment variables in the setup.
+1. Download and install the Ogre SDK and the precompiled VC dependencies: http://www.ogre3d.org
+1. Set the environment variable OGRE_HOME to where the the Ogre SDK is installed
+1. Open "Visual Studio 2005 Command Prompt" and navigate to where you have Ogre.rb checked out and run the following rake tasks
+
+==== Build
+
+1. rake ogre:swig
+1. rake ogre:compile
+1. rake ois:swig
+1. rake ois:compile
+	
+You cannot run rake ogre:build or ois:build due to a Windows file permission problem.
+
+The resulting files can be found in ogrerb/lib.
+
+== Running Ogre.rb programs
+
+You'll either have to copy the OgreMain dll to the ogrerb/lib folder, or you'll need to set the PATH (on Windows) or LD_LIBRARY_PATH (on Linux) environment variable to point to where this file is ([OgreSDK]/bin/release for prebuilt). Then, it's simply <code>require 'ogre'</code> and off you go.

data/Rakefile

@@ -0,0 +1,288 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/contrib/sshpublisher'
+require 'rake/gempackagetask'
+
+require 'platform'
+
+task :default => :build_all
+
+OGRE_RB_VERSION = "0.1"
+
+###########################
+# Project Managment tasks #
+###########################
+
+RDOC_INCLUDES = %w(
+	README
+	doc_src/**/*.rb
+	lib/application.rb
+	lib/application_frame_listener.rb
+	lib/application_loading_bar.rb
+	lib/constants.rb
+	lib/method_fixes.rb
+)
+
+RDOC_OPTIONS = ['-S', '-t Ogre.rb Documentation']
+
+Rake::RDocTask.new do |t|
+  t.main = "README"
+	t.rdoc_files.include(RDOC_INCLUDES)
+	t.options += RDOC_OPTIONS
+end
+
+RUBYFORGE_USERNAME = "jameskilton"
+PROJECT_WEB_PATH = "/var/www/gforge-projects/ogrerb"
+
+desc "Update the website" 
+task :upload_web => :rdoc  do |t|
+  unless File.directory?("publish")
+    mkdir "publish"
+    mkdir "publish/docs"
+  end
+  sh "svn export --force website publish/"
+  sh "cp -r html/* publish/docs/"
+	Rake::SshDirPublisher.new("#{RUBYFORGE_USERNAME}@rubyforge.org", PROJECT_WEB_PATH, "publish").upload
+  rm_rf "publish"
+end
+
+## Gem Compilation ##
+ogre_rb_spec = Gem::Specification.new do |s|
+
+	s.platform = Gem::Platform::CURRENT
+
+	lib_files = ""
+	if Platform.windows?
+		lib_files = %w(lib/ogre.dll lib/ruby_ois.dll)	
+	elsif Platform.mac?
+	else # Posix environment
+		lib_files = %w(lib/ogre.so lib/ruby_ois.so)
+	end
+
+  s.name = 'ogre.rb'
+  s.version = OGRE_RB_VERSION
+  s.summary = "Ruby wrapper for Ogre 3D"
+  s.description = %q{Ogre.rb is a SWIG wrapper to allow access to the Ogre 3D API from Ruby.}
+
+  s.author = "Jason Roelofs"
+  s.email = "jameskilton@gmail.com"
+  s.rubyforge_project = 'ogrerb'
+  s.homepage = 'http://ogrerb.rubyforge.org'
+
+  s.require_path = '.'
+
+	s.required_ruby_version = '>= 1.8.4'
+
+	# Inform of the need to have Ogre installed and OGRE_HOME set
+	s.requirements << "Ogre Einhort (1.4)"
+	s.requirements << "Environment variable OGRE_HOME set"
+
+  #s.has_rdoc = false
+  #s.extra_rdoc_files += RDOC_INCLUDES
+  #s.rdoc_options += RDOC_OPTIONS
+
+  files = FileList.new %W[
+		README
+		platform.rb
+		ogre.rb
+		Rakefile
+		lib/*.rb
+		samples/**/*
+		doc_src/**/*	
+  ]
+	files += lib_files
+
+	s.files = files
+end
+
+desc 'Package as gem & zip'
+Rake::GemPackageTask.new(ogre_rb_spec) do |p|
+  p.gem_spec = ogre_rb_spec
+  #p.need_tar = true
+  #p.need_zip = true
+end
+
+#############################
+# Project compilation tasks #
+#############################
+
+desc "Rebuild the OGRE and OIS wrappers"
+task :build_all => ["ogre:build", "ois:build"]
+
+desc "Clean everything"
+task :clean_all => ["ogre:clean", "ois:clean"]
+
+namespace :ois do
+  desc "Rebuild all of the OIS wrapper"
+  task :build => [:swig, :compile]
+
+  desc "Run swig on the interface files"
+  task :swig do
+    includes = %w(-I./src_headers/OIS -I./src_headers/wrappers)
+    sh "swig -ruby -minherit -c++ -autorename #{includes.join(' ')} -o build/ois/ois_wrap.cpp ois/ois.i" 
+    if Platform.windows?
+    	insert_headers("build/ois/ois_wrap.cpp") do
+    		<<-EOF
+    			#include "OIS.h"
+    		EOF
+    	end
+  	end
+  end
+
+  desc "Compile the extension and move the resulting library into lib/"
+  task :compile do
+		resulting_file = "ruby_ois.so"
+		build_file = resulting_file
+	  cd "build/ois" do
+	    ruby "extconf.rb"
+	  	if Platform.linux? 
+		    sh "make all"
+		  elsif Platform.windows?
+				sh "nmake"
+				# Create our manifest (see http://www.codeproject.com/cpp/vcredists_x86.asp)
+				sh "mt.exe /manifest #{resulting_file}.manifest /outputresource:#{resulting_file};#2"
+				resulting_file = "ruby_ois.dll"
+				build_file = "ruby_ois.so"
+			else
+				raise "Error: Unsupported platform " + PLATFORM
+			end
+  	  cp build_file, File.join("..", "..", "lib", resulting_file)
+  	end
+  end
+
+  desc "Clean up the build environment"
+  task :clean do
+    cd "build/ois" do
+      ruby "extconf.rb"
+      sh "make clean"
+      rm "mkmf.log" rescue nil
+    end
+  end
+end
+
+namespace :ogre do
+
+  desc "Rebuild all of ogre.rb"
+  task :build => [:swig, :compile]
+
+  desc "Run swig on the interface files"
+  task :swig do
+    includes = %w(-I./src_headers/OGRE -I./src_headers/ExampleApplication -I./src_headers/wrappers -I./src_headers/OIS)
+    sh "swig -ruby -minherit -c++ -autorename #{includes.join(' ')} -o build/ogre/ogre_rb_wrap.cpp ogre/ogre_rb.i" 
+    if Platform.windows?
+    	# compensate for windows stl.  Uses wrong version when ruby is first.
+    	insert_headers("build/ogre/ogre_rb_wrap.cpp") do
+    		<<-EOF
+					#include "Ogre.h"
+					#{Platform.windows? ? "#include <winsock.h>" : ""}
+				EOF
+  		end
+    end
+  end
+
+  desc "Compile the extension and move the resulting library into lib/"
+  task :compile do
+		resulting_file = "ogre.so"
+	  cd "build/ogre" do
+	    ruby "extconf.rb"
+	  	if Platform.linux? 
+		    sh "make clean all"
+		  elsif Platform.windows?
+				sh "nmake"
+				# Create our manifest (see http://www.codeproject.com/cpp/vcredists_x86.asp)
+				sh "mt.exe /manifest ogre.so.manifest /outputresource:ogre.so;#2"
+				resulting_file = "ogre.dll"
+			else
+				raise "Error: Unsupported platform " + PLATFORM
+			end
+  	  cp "ogre.so", File.join("..", "..", "lib", resulting_file)
+  	end
+  end
+
+  desc "Clean up the build environment"
+  task :clean do
+    cd "build/ogre" do
+      ruby "extconf.rb"
+      sh "make clean"
+      rm "mkmf.log" rescue nil
+    end
+  end
+
+  desc "Copy over the ogre header files from an ogre installation. Expects OGRE_HOME to be set."
+  task :update_headers do
+    raise "Unable to find Ogre headers, please set OGRE_HOME to the distribution path" if ENV['OGRE_HOME'].nil? 
+
+    File.cp_r "#{ENV['OGRE_HOME']}/include/OGRE/", "#{File.dirname(__FILE__)}/src_headers"
+  end
+
+  desc "Create default interface files for each of the ogre headers" 
+  task :create_interfaces do
+    headers_match = File.join("src_headers", "OGRE", "Ogre*.h")
+    ogre_headers = Dir[headers_match]
+
+    ogre_headers.each do |header|
+      filename = File.basename(header, ".h")
+      interface_file_name = File.join("ogre", File.basename(header, ".h") + ".i")
+      raise "Interface file for #{filename} already exists" if File.exists?(interface_file_name)
+
+      File.open(interface_file_name, "w+") do |file|
+        file.write <<END
+%{
+  #include "#{filename}.h"
+%}
+
+%include "#{filename}.h"
+END
+      end
+    end
+  end
+end
+
+
+namespace :navi do
+
+  desc "Rebuild all of navi.rb"
+  task :build => [:swig, :compile]
+
+  desc "Run swig on the interface files"
+  task :swig do
+    includes = %w(-I./src_headers/navi -I./src_headers/wrappers)
+    sh "swig -autorename -ruby -minherit -c++ #{includes.join(' ')} -o build/navi/navi_rb_wrap.cpp navi/navi_rb.i" 
+    if Platform.windows?
+    	# compensate for windows stl.  Uses wrong version when ruby is first.
+    	
+    	insert_headers("build/navi/navi_rb_wrap.cpp") do
+    		<<-EOF
+					#include "Ogre.h"
+					#{Platform.windows? ? "#include <winsock.h>" : ""}
+				EOF
+  		end
+    end
+  end
+
+  desc "Compile the extension and move the resulting library into lib/"
+  task :compile do
+		resulting_file = "navi.dll"
+	  cd "build/navi" do
+	    ruby "extconf.rb"
+	  	if Platform.windows?
+				sh "nmake"
+				# Create our manifest (see http://www.codeproject.com/cpp/vcredists_x86.asp)
+				sh "mt.exe /manifest navi.so.manifest /outputresource:navi.so;#2"
+			else
+				raise "Error: Unsupported platform " + PLATFORM
+			end
+  	  cp "navi.so", File.join("..", "..", "lib", resulting_file)
+  	end
+  end
+
+  desc "Clean up the build environment"
+  task :clean do
+    cd "build" do
+      ruby "extconf.rb"
+      sh "make clean"
+      rm "mkmf.log" rescue nil
+    end
+  end
+
+end

data/doc_src/ogre.rb

@@ -0,0 +1,246 @@
+#
+# = Naming Conventions
+#
+# Ogre.rb is using the <tt>--autorename</tt> flag available in SWIG-Ruby. This automatically
+# renames constants, methods, and attributes to follow the Ruby Way. Mainly, this means that
+# method names are the same as Ogre's, but follow this style:
+#
+#   ClassName.method_name(param1, param2, ...)
+#   var.method_name?   # for methods who return boolean results
+#
+# Because there are setter methods in Ogre that can take multiple parameters 
+# (e.g. SceneManager::setSkyBox), we've decided to not turn set/get methods into the typical 
+# attr_accessor names of Ruby. So, this method would be used in Ogre.rb as such:
+# 
+#   scene_manager.set_sky_box(true, "CloudySky")
+#
+# This documentation will try to cover every method rename that differs from straight undercasing of Ogre method names,
+# though please post a patch if some are missed.
+#
+module Ogre
+	# This class is here to define a few things that were difficult / not
+	# working correctly just through SWIG. These methods are defined so as not to be any different
+	# from calling the constants straight from Ogre (Vector3.ZERO).
+	#
+	# See OgreVector3.i for an example, but basically we need to define these manually
+	# because Ruby always passes references, which causes annoying problems such as:
+	#
+	#   vec1 = Ogre::Vector3.ZERO
+	#   vec1.x = 10 
+	#   vec2 = Ogre::Vector3.ZERO
+	#   vec2.x        #=> 10 (when it should be 0)
+	#  
+	# Current classes with constants redefined as methods in lib/constants.rb: 
+	#
+	#   Vector3
+	#   Vector4
+	#   Quaternion
+	#
+	module Constants
+	end
+	
+	class FrameEvent
+		# Function wrapper for the timeSinceLastFrame variable
+		def time_since_last_frame
+		end
+
+		# Function wrapper for the timeSinceLastEvent variable
+		def time_since_last_event
+		end
+	end
+
+  # As it stands, all classes with internal Listener classes (aka Resource) have been neutered to not
+  # allow access to these inner classes. As Ruby is perfectly fine with inner classes, this may need
+  # to be a change to the ruby SWIG driver. So for now, these classes and the related functions
+  # are unavailable through Ogre.rb.
+  class Listeners
+  end
+
+  # MovableObject is used extensively in Ogre, but very rarely is an instance of the class created through
+  # the typical "new MovableObject();" syntax. Given this, there is no immedate way of knowing what subclass
+  # of MovableObject was actually created, in say, Ogre::SceneManager::createMovableObject:
+  #
+	#	  virtual MovableObject* createMovableObject(const String& name, const String& typeName, const NameValuePairList* params = 0);
+  #
+  # Left alone, every call to this function will return a MovableObject instance instead of the appropriate
+  # subclass, completely destroying expected type information. Thankfully Ogre makes this very easy to 
+  # solve: getMovableType. Every MovableObject has this method which returns the string representation
+  # of the class name it is. Using this string, we can find out what class was actually created and have
+  # SWIG generate the appropriate class type. Thus, we can do the following:
+  #
+  #   trail = scene_manager.create_movable_object("RibbonTrail1", "RibbonTrail", {"numberOfChains" => "2", "maxElements" => "80"}) 
+  #   trail.set_material_name("LightRibbonTrail")
+  #   trail.set_trail_length(400)
+  #
+  # As <tt>trail</tt> is a <tt>#<Ogre::RibbonTrail:0xb6edf718></tt>.
+  #
+  class MovableObject
+  end
+
+  # Any method call that takes an Ogre::NameValuePairList argument should be given a normal Ruby
+  # hash of "key" => "value". Example usage is found in the sample lighting.rb.
+  #
+  # Ogre's SceneManager::createMovableObject is defined as:
+  #
+	#	  virtual MovableObject* createMovableObject(const String& name, const String& typeName, const NameValuePairList* params = 0);
+  #
+  # and can be used in Ogre.rb as:
+  #
+  #   trail = scene_manager.create_movable_object("RibbonTrail1", "RibbonTrail", {"numberOfChains" => "2", "maxElements" => "80"}) 
+  #
+  class NameValuePairList
+  end
+
+	class RenderWindow
+		# Renamed: isClosed
+		def closed?
+		end
+	end
+
+	class Singleton
+		# Renamed: getSingleton
+		#
+		# In following the Ruby-way, singletons are to be accessed as such:
+		#
+		#   MeshManager.instance.create_mesh
+		#
+		def self.instance
+		end
+	end
+
+	class SceneManager
+		# Renamed: getRootSceneNode
+		def root_scene_node
+		end
+	end
+
+  class TextureManager
+    # There is currently an issue with create_manual in that if you try to use the 
+    # method version that does not include the depth parameter (such as in Ogre's 
+    # RenderToTexture demo), SWIG still chooses this
+    # one, sending in the render_type parameter as the pixel_format. If you run into an unexpected
+    # assert failure in PixelFormat, make sure that you're method call
+    # signature matches this method's parameter list.
+    #
+    # num_mip_maps can be -1 to use the system's default number of mip maps
+    #
+    # depth must be >= 1 or the method will never return
+    #
+    # Ogre's docs for this class are here: http://www.ogre3d.org/docs/api/html/classOgre_1_1TextureManager.html
+    def create_manual(name, group_name, tex_type, width, height, depth, num_mip_maps, pixel_format, render_type, manual_loader = nil)
+    end
+  end
+
+	# There is a problem, possibly unsolvable, with trying to send Ruby subclasses of C++ classes
+	# back into C++ methods. This came up in situations like registering a custom FrameListener. 
+	# It basically doesn't work, and ends up causing all sorts of issues from random SegFaults at
+	# runtime to ObjectPreviouslyDeleted errors at the method's invocation. To get around this 
+	# problem, these proxy classes have been defined. They are simple C++ subclasses that take
+	# care of whatever registering needs to happen inside of their constructor. 
+	#
+	# Also please note: <b>This Proxies namespace does not exist in Ogre.rb</b>. The classes are grouped
+	# this way for documentation purposes.
+	module Proxies
+		# FrameListenerProxy constructor takes the Root object, with which it registers itself as a system
+		# frame listener.
+		class FrameListenerProxy
+			def initialize(root)
+			end
+		end
+
+		# This proxy isn't quite done yet, as it's registering command, 
+		# WindowEventUtilities::addWindowEventListener, takes both the Listener and a RenderWindow. 
+		# It's the RenderWindow that is causing problems but I think this one is easily solvable.
+		class WindowEventListenerProxy
+			def initialize(render_window)
+			end
+		end
+	end
+
+	# Hardware buffers are an especially interesting problem when it comes to duplicating functionality in Ruby. 
+	# Buffers like Vertex and Index buffers are meant to be directly accessible and in a contiguous memory location.
+	# This allows the Ogre C++ code to populate these buffers as such
+	#
+	#   // position
+	#   *pReal++ = -vec.x;
+	#   *pReal++ = GRASS_HEIGHT;
+	#   *pReal++ = -vec.z;
+	#   // normal
+	#   *pReal++ = 0;
+	#   *pReal++ = 1;
+	#   *pReal++ = 0;
+	#   // uv
+	#   *pReal++ = 0;
+	#   *pReal++ = 0;
+  #
+	# Now we obviously can't do this in Ruby, so Vertex and Index Buffer proxy classes have been put together to 
+	# allow the above code to become this following in Ruby
+	#
+	#   x = i * 32
+	#   # Position
+	#   reals[x + 0] = -vec.x
+	#   reals[x + 1] = GRASS_HEIGHT
+	#   reals[x + 2] = -vec.z
+	#   # Normal
+	#   reals[x + 3] = 0
+	#   reals[x + 4] = 1	
+	#   reals[x + 5] = 0
+	#   # UV
+	#   reals[x + 6] = 0
+	#   reals[x + 7] = 0
+	#
+	# Compare the Ogre Grass demo with the Ogre.rb Grass demo to see the full code
+	class HardwareBuffer
+	end
+	
+	# See HardwareBuffer
+	class HardwareVertexBuffer < HardwareBuffer
+		# For now this should be the only lock method used. It returns a VertexBufferProxy which
+		# allows the array-like access
+		def lock(lock_options)
+		end
+	end
+
+	# See HardwareBuffer
+	class HardwareIndexBuffer < HardwareBuffer
+		# For now this should be the only lock method used. It returns an IndexBufferProxy which
+		# allows the array-like access
+		def lock(lock_options)
+		end
+	end
+
+
+	# The StaticGeometry class contains a lot of nested classes to deal with all of the parts that could possible
+	# be in a piece of static geometry. This of course poses a serious problem with wrapping as SWIG cannot handle
+	# nested classes. The solution here is to create proxy classes for all of the nested classes and use those instead.
+	# The normal API of using StaticGeometry has not changed, just the names of the classes that will be dealt with.
+	#
+	# This proxy code was taken from OgreDotNet and still needs some work to make it fit nicely into the Ruby way of
+	# doing things. If something isn't quite right, please look at OgreStaticGeometry.i and StaticGeometryProxies.h
+	# to see what methods are available.
+	#
+	# See the Grass demo for example usage.
+	class StaticGeometry
+		# Proxy for the StaticGeometry::GeometryBucket class
+		class SGGeometryBucket
+			# Returns the underlying GeometryBucket class as a Renderable object
+			def as_renderable
+			end
+		end
+
+		# Proxy for the StaticGeometry::MaterialBucket class
+		class SGMaterialBucket
+		end
+
+		# Proxy for the StaticGeometry::LODBucket class
+		class SGLODBucket
+		end
+
+		# Proxy for the StaticGeometry::Region class
+		class SGRegion
+			# Returns the underlying Region class as a MovableObject
+			def as_movable_object
+			end
+		end
+	end
+end

data/doc_src/ois.rb

@@ -0,0 +1,67 @@
+# OIS has been completely wrapped into Ruby. Any of OIS's classes documented here are to describe
+# special cases or functionality changes required to make this work for Ruby.
+module OIS
+
+	class InputManager
+		# As with Ogre::MovableObject and Ogre::Resource, the usage of <tt>create_input_object</tt> will automatically
+		# return the proper type of OIS::Object whether it be a Mouse, Keyboard, or JoyStick.
+		#
+		# See Ogre::ApplicationFrameListener for an example of where this is used.
+		def create_input_object(obj_type, is_buffered)
+		end
+
+		# See OIS::ParamList
+		def create_input_system(param_list)
+		end
+	end
+
+	class Keyboard
+		# Renamed: isKeyDown
+		def key_down?(key)
+		end
+	end
+
+	class Mouse
+		# Renamed: getMouseState
+		def mouse_state
+		end
+	end
+
+	class MouseState
+		# Renamed: buttonDown
+		def button_down?(button)
+		end
+	end
+
+	# Any OIS function that uses a ParamList as a parameter type will now require a simple Ruby
+	# hash construct. For example, <tt>InputManager.createInputSystem</tt> is now used as such:
+	#
+	#   windowHnd = @window.get_custom_attribute_unsigned_long("WINDOW")
+	#   InputManager.create_input_system( { "WINDOW" => "#{windowHnd}" } )
+	#
+	# With <tt>create_input_system</tt>, the version that simply takes a size_t has been disabled because it
+	# was causing problems.
+	class ParamList
+	end
+
+	# See Ogre::Proxies for an explaination of the existance of these classes. See src_headers/wrappers/OISProxies.h.
+	#
+	# Also please note: <b>This Proxies namespace does not exist in Ogre.rb</b>. The classes are grouped this way
+	# for documentation purposes.
+	module Proxies
+		class KeyListenerProxy
+			def initialize(keyboard)
+			end
+		end
+
+		class MouseListenerProxy
+			def initialize(mouse)
+			end
+		end
+
+		class JoyStickListenerProxy
+			def initialize(joy_stick)
+			end
+		end
+	end
+end