ogre.rb

= 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.4 (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. All patches will be considered but those with tests, if possible, are recommended.

== Build Requirements

• rake
• Ogre 1.4.4 (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

rake build_all

If you get an error about OIS framework not being installed, you can download a build of the OIS framework here: http://www.shatteredruby.com/support/OIS.1.0.framework.zip.* Place it into your /Library/Frameworks directory.

After building, the resulting frameworks will be located in ogrerb/lib.

You will need to run the build_mac_rubyw Rake task, which creates a rubyw executable that's fit for opening up windows in the foreground. See http://rubyforge.org/forum/forum.php?thread_id=15371&forum_id=14174 for details.

Remember once you do this to start ogrerb programs with 'rubyw' instead of 'ruby', otherwise keyboard input will be disabled.

*The OIS framework is made by wreckedgames.com, and the sourceforge project page is here: http://sourceforge.net/projects/wgois. The build in this document is for convenience only and is not an official release.

=== Windows

==== Setup your environment

1. Install Ruby One-Click Installer: http://rubyforge.org/projects/rubyinstaller/
2. Install Visual Studio Express 2005: http://msdn.microsoft.com/vstudio/express/ (Be sure to register environment variables)
3. 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
4. You need the MS platform SDK available here(ish): http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en.
5. Be sure to register environment variables in the setup.
6. Download and install the Ogre SDK and the precompiled VC dependencies: http://www.ogre3d.org
7. Set the environment variable OGRE_HOME to where the the Ogre SDK is installed
8. 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
2. rake ogre:compile
3. rake ois:swig
4. 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 require 'ogre' and off you go.

== Testing Ogre.rb programs

test/test_helper.rb contains the minimum needed setup for Ogre to properly allow testing of it's components.

== Notes

These are the classes currently not wrapped for various reasons:

• OgreConfigDialog
• OgreConfig
• OgreConfigOptionMap
• OgreErrorDialog
• OgreException
• OgreProfiler
• OgreStringConverter
• OgreZip
• OgreAlignedAllocator
• OgreBitwise
• OgreMemoryManager
• OgreFileSystem
• OgreUnifiedHighLevelGpuProgram
• OgreSearchOps
• OgreStableHeaders
• OgreUTFString
• OgreILCodecs
• OgreILImageCodec
• OgreILUtil