md2 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,26 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+.idea
+*.bundle
+*.o
+*.out
+Makefile

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Colin MacKenzie IV
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,174 @@
+= md2
+
+A Ruby library for loading MD2 (Quake II) 3D model files. It doesn't actually render them; that part is up to you.
+
+== Installation
+
+  gem install md2
+  
+== Usage
+
+  require 'md2'
+  
+  md2 = MD2.new("/path/to/md2")
+  md2.frames.each_with_index do |frame, index|
+    puts frame.name
+    puts frame.vertices.length
+    puts frame.normal_indices
+  end
+  puts md2.triangles.length
+  puts md2.texcoords.length
+  # and so on.
+  
+See the MD2 class documentation for more, or scroll down for an example of how to render the model.
+
+== Converting to JSON
+
+The MD2 library works great with the 'json' gem. Just load an MD2 and then call #to_json:
+
+  require 'md2'
+  require 'json'
+  
+  md2 = MD2.new("/path/to/md2")
+  json = md2.to_json
+  
+I think this will be pretty cool as WebGL and friends begin to take off. I've also added a generator for this. You can
+convert an MD2 file into its JSON counterpart at the command line with:
+
+  $ md2_to_json /path/to/md2 >/path/to/json
+  
+The generator just prints the JSON to stdout (which made it easier for me to test), so you have to redirect the output
+into a file if you want to capture it.
+
+  The ">" in the command above is used to redirect stdout. Check Wikipedia for
+  Redirection (computing) for more details if you've never seen this before:
+  http://en.wikipedia.org/wiki/Redirection_(computing)
+  
+=== About the JSON output
+
+First, here's the general structure of a JSON string created by this library:
+
+  {
+    "header": {
+      "skin_width":256, "skin_height":256, "skin_count":0, "frame_count":199,
+      (other header data that was previously used for loading the model)
+    },
+    "frames": {[
+      {"name"          : "Frame1",
+       "translation"   :[ (XYZ float array) ],
+       "scale"         :[ (XYZ float array) ],
+       "vertices"      :[ (array of vertex data: these are INTEGERS! - see below) ],
+       "normal_indices":[array of normal indices]
+      },
+      ...
+    ]},
+    "triangles":[
+      {"vertex_indices"  :[ (XYZ int array) ],
+       "texcoord_indices":[ (ST int array) ]},
+      ...
+    ],
+    "texcoords":[
+      [ (ST float array) ],
+      [ (ST float array) ],
+      [ (ST float array) ],
+      ...
+    ],
+    "skins": [ (string array of filenames) ],
+    "gl_commands": [
+      { "texture_s": float,
+        "texture_t": float,
+        "vertex_index": int },
+      ...
+    ]
+  }
+    
+Now that you can see the general flow of the JSON, here's a bit more info:
+
+The header info is generally not useful to you and consists mostly of information that was read from the MD2 file when
+it was initially loaded.
+
+Frames are one potential gotcha: the vertex information stored in the frame is an integer between 0 and 255. This
+integer is useless on its own; you need to expand the vertex data from it by first multiplying by scale, and then
+adding translation. The vertex count is divisible by 3 because -- you guessed it -- every first vertex is X, every
+second is Y and every third is Z. The reason for all of this? Because when I tried to precalculate it all for you,
+the JSON result was 4 times bigger! A 250KB MD2 file resulted in over 4MB of JSON. By letting you do this on your
+end, I'm saving you a ton of bandwidth. If you go another step and gzip compress the current result, it actually ends
+up smaller than the original MD2 file!
+
+* Note that the vertex data is already unpacked for you if you're using just the Ruby library; the vertex information
+  is only packaged this way in JSON, to reduce bandwidth requirements.
+
+So here's a code snippet of how to extract the vertex information in JavaScript. Copy and paste to your heart's content!
+  /* assume we have a JSON object called 'model' */
+  for (var frame_index = 0; frame_index < model.frames.length; frame_index++)
+  {
+    var vertices = [];
+    var frame = model.frames[frame_index];
+    for (var vert_index = 0; vert_index < frame.vertices.length; vert_index += 3)
+      for (var k = 0; k < 3; k++)
+        vertices[vert_index+k] = (frame.vertices[vert_index+k] * frame.scale[k]) + frame.translation[k];
+    /* we have the unpacked vertex data; may as well just replace the now-useless packed data */
+    frame.vertices = vertices;
+  }
+  
+Nothing else in the JSON output is packed in this way. The texture coordinate indices point to the "texcoords"
+array, and the normal indices point to the precomputed MD2 normals. If you need to implement those in JavaScript,
+take a look at the MD2::Normals constant for the data.
+
+Triangles are made up of 3 vertices (each with an X, Y, Z coordinate) and 3 texture coordinates (each with an S, T
+coordinate); therefore, they consist of 3 vertex indices (which reference the frame vertices you just unpacked) and
+3 texture coordinate indices.
+
+The texcoords array consists of a number of nested arrays. Each nested array has 2 elements, the S and T value for
+that texture coordinate. The nesting is designed to make it easier for you to access via coordinate indices (see
+Triangles, above).
+
+Skins are simply a list of filenames (Strings) referenced within the MD2. Do what you will with them.
+
+The final component, gl_commands, is discussed below. The code is in Ruby, but the approach is the same.
+
+== Note on Rendering
+
+The preferred way to render an MD2 file is to make use of its GL Commands, which produce an optimized approach to
+rendering by switching between triangle strips and triangle fans (as opposed to just rendering the entire model with
+only triangles). This library parses the command information into an intuitive structure so you don't have to deal
+with the nuances of the format. Instead, here's how you would go about rendering an MD2 using its GL commands:
+
+  frame = md2.frames[current_frame]
+  
+  md2.gl_commands.each do |command|
+    case command.type
+      when :triangle_strip then glBegin(GL_TRIANGLE_STRIP)
+      when :triangle_fan   then glBegin(GL_TRIANGLE_FAN)
+    end
+    
+    command.segments.each do |segment|
+      index = segment.vertex_index
+    
+      glTexCoord2f(segment.texture_s, segment.texture_t)
+      glNormal3f(frame.normals[index].x, frame.normals[index].y, frame.normals[index].z)
+      glVertex3f(frame.vertices[index].x, frame.vertices[index].y, frame.vertices[index].z)
+    end
+    
+    glEnd
+  end
+  
+== Limitations
+
+Modifying and saving the MD2 file is not currently supported, although this may be implemented sometime in the future.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Colin MacKenzie IV. See LICENSE for details.
+
+http://thoughtsincomputation.com

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "md2"
+    gem.summary = %Q{A Ruby library for loading MD2 3D model files.}
+    gem.description = %Q{A Ruby library for loading MD2 3D model files.}
+    gem.email = "sinisterchipmunk@gmail.com"
+    gem.homepage = "http://thoughtsincomputation.com"
+    gem.authors = ["Colin MacKenzie IV"]
+    gem.add_dependency "sizes", ">= 1.0"
+    gem.add_dependency "activesupport", ">= 2.3.5"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+begin
+  require 'spec/rake/spectask'
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.spec_files = FileList['spec/**/*_spec.rb']
+  end
+  
+  Spec::Rake::SpecTask.new(:rcov) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.pattern = 'spec/**/*_spec.rb'
+    spec.rcov = true
+  end
+  
+  task :spec => :check_dependencies
+  
+  task :default => :spec
+rescue LoadError
+  puts "It seems you don't have rspec 1.x. You won't be able to run the test suite."
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "md2 #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/md2_to_json

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+def banner
+  puts "Usage:"
+  puts "\truby md2_to_json.rb path/to/input.md2"
+  puts
+end
+
+unless ARGV.length == 1
+  banner
+  puts "Output is printed to stdout. To capture json output, redirect"
+  puts "to file:"
+  puts
+  puts "\truby md2_to_json.rb path/to/input.md2 >path/to/output.md2"
+  puts
+  exit
+end
+
+if File.file?(filename = ARGV.first)
+  require 'rubygems'
+  gem 'json'
+  
+  require File.join(File.dirname(__FILE__), '../lib/md2')
+  require 'json'
+  md2 = MD2.new(filename)
+  puts md2.to_json
+else
+  puts
+  puts "!! File '#{filename}' does not exist !!"
+  puts
+  banner
+  exit
+end

data/ext/md2/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+
+create_makefile 'md2'

data/ext/md2/md2.c

@@ -0,0 +1,95 @@
+#include "ruby.h"
+
+static VALUE read_gl_commands_ext(VALUE self, VALUE gl_command_count, VALUE gl_command_offset, VALUE gl_command_data);
+static VALUE construct_command(VALUE args);
+static VALUE cMD2 = Qnil;
+
+void Init_md2()
+{
+  cMD2 = rb_define_class("MD2", rb_cObject);
+  rb_define_method(cMD2, "read_gl_commands_ext", read_gl_commands_ext, 3);
+}
+
+/*
+Accepts a command count, command offset and filename. The file is opened and the data is read;
+an argument error is raised if the file could not be opened or if the exact command count could
+not be read from the file. Otherwise, the data is deserialized according to the MD2::Command
+documentation and then it is returned as an array of MD2::Command instances.
+
+See the documentation for MD2::Command for the exact algoritm; I couldn't figure out how to
+implement it using pure Ruby.
+*/
+static VALUE read_gl_commands_ext(VALUE self, VALUE gl_command_count, VALUE gl_command_offset, VALUE file_path)
+{
+  char *cpath = StringValueCStr(file_path);
+  FILE *inf = fopen(cpath, "r");
+  if (!inf) rb_raise(rb_eArgError, "Could not open file %s to read GL command data!", cpath);
+  
+  unsigned int command_count = FIX2INT(gl_command_count);
+  int command_offset = FIX2INT(gl_command_offset);
+  int *cdata = (int *)malloc(sizeof(int) * command_count);
+  
+  fseek(inf, command_offset, SEEK_SET);
+  if (fread(cdata, sizeof(int), command_count, inf) != command_count)
+  {
+    fclose(inf);
+    free(cdata);
+    rb_raise(rb_eArgError, "Could not read %d GL commands from file", command_count);
+  }
+  fclose(inf);
+  
+  VALUE ary = rb_ary_new();
+  int i = 0, error;
+  int val;
+  while ((val = cdata[i++]) != 0)
+  {
+    int count;
+    if (val > 0) count = val;
+    else count = -val;
+    
+    VALUE sym;
+    const char *symcstr;
+    if (val > 0) sym = ID2SYM(rb_intern("triangle_strip"));
+    else sym = ID2SYM(rb_intern("triangle_fan"));
+
+    // construct the packet which will contain the args to be sent to MD2::Command
+    VALUE packet = rb_ary_new();
+    // add the render type to the packet
+    rb_ary_push(packet, sym);
+    
+    while (count--)
+    {
+      float s = *(float *)&cdata[i++];
+      float t = *(float *)&cdata[i++];
+      int index = cdata[i++];
+    
+      // add s, t, index to the packet
+      rb_ary_push(packet, rb_float_new(s));
+      rb_ary_push(packet, rb_float_new(t));
+      rb_ary_push(packet, INT2FIX(index));
+    }
+    
+    // construct the MD2::Command from the packet data. If error,
+    // intercept it and then break so that we can free cdata properly.
+    VALUE command = rb_protect(construct_command, packet, &error);
+    if (error) break;
+    
+    // store the command in the resultant array
+    rb_ary_push(ary, command);
+  }
+  
+  free(cdata);
+  
+  // now that cdata is taken care of, re-raise the error if there was one
+  if (error)
+    rb_exc_raise(rb_gv_get("$!"));
+  
+  return ary;
+}
+
+static VALUE construct_command(VALUE args)
+{
+  VALUE cMD2Command = rb_const_get(cMD2, rb_intern("Command"));
+  VALUE command = rb_funcall2(cMD2Command, rb_intern("new"), 1, &args);
+  return command;
+}

data/lib/md2.rb

@@ -0,0 +1,97 @@
+$:.unshift(File.dirname(__FILE__))
+require File.join(File.dirname(__FILE__), "../ext/md2/md2")
+require 'sizes'
+require 'active_support/core_ext'
+
+class MD2
+  include Sizes
+  
+  autoload :Header,   "md2/header"
+  autoload :Errors,   "md2/errors"
+  autoload :Frame,    "md2/frame"
+  autoload :Vertex,   "md2/vertex"
+  autoload :Triangle, "md2/triangle"
+  autoload :Command,  "md2/command"
+  autoload :Normals,  "md2/normals"
+  
+  attr_reader :header
+  attr_reader :base_path, :frames, :triangles, :skins, :texcoords, :gl_commands
+  
+  delegate :skin_width, :skin_height, :frame_size, :skin_count, :vertex_count,
+           :texture_coord_count, :triangle_count, :gl_command_count, :frame_count,
+           :skin_name_offset, :texture_coord_offset, :triangle_offset, :frame_data_offset,
+           :gl_command_offset, :eof_offset, :to => :header
+  
+  def initialize(path)
+    load(path)
+  end
+  
+  def to_json
+    raise "Can't convert to json unless you've already activated the 'json' gem!" if !defined?(JSON)
+    
+    {
+      :header => @header,
+      :frames => @frames.collect { |f| f.reduce },
+      :triangles => @triangles,
+      :texcoords => @texcoords,
+      :skins => @skins,
+      :gl_commands => @gl_commands,
+      :base_path => @base_path
+    }.to_json
+  end
+  
+  private
+  def load(path)
+    @base_path = File.dirname(path)
+    File.open(path, "rb") do |file|
+      read_header(file)
+      read_frames(file)
+      read_triangles(file)
+      read_skins(file)
+      read_texcoords(file)
+    end
+    @gl_commands = read_gl_commands_ext(gl_command_count, gl_command_offset, path)
+  end
+  
+  def read_header(file)
+    @header = MD2::Header.new(file)
+  end
+  
+  def read_frames(file)
+    @frames = []
+    read_data(file, frame_data_offset, frame_count, frame_size) do |chunk|
+      @frames << MD2::Frame.new(chunk)
+    end
+  end
+
+  def read_triangles(file)
+    @triangles = []
+    read_data(file, triangle_offset, triangle_count, 6 * sizeof(:short)) do |chunk|
+      @triangles << MD2::Triangle.new(chunk)
+    end
+  end
+  
+  def read_skins(file)
+    @skins = []
+    read_data(file, skin_name_offset, skin_count, sizeof(:char)*64) do |chunk|
+      @skins << chunk.strip
+    end
+  end
+  
+  def read_texcoords(file)
+    @texcoords = []
+    read_data(file, texture_coord_offset, texture_coord_count, sizeof(:short)*2) do |chunk|
+      @texcoords << chunk.unpack("s2")
+      @texcoords.last[0] = @texcoords.last[0] / skin_width.to_f
+      @texcoords.last[1] = @texcoords.last[1] / skin_height.to_f
+    end
+  end
+  
+  def read_data(file, offset, count, chunk_size)
+    file.sysseek(offset)
+    data = file.sysread(count * chunk_size)
+    count.times do |num|
+      yield data[(num*chunk_size)...(num*chunk_size+chunk_size)]
+    end
+  end
+end