jax 1.0.1 → 1.1.0.rc1

data/.gitmodules

@@ -1,3 +1,6 @@
 [submodule "vendor/pdoc"]
 	path = vendor/pdoc
 	url = git://github.com/tobie/pdoc.git
+[submodule "vendor/jasmine"]
+	path = vendor/jasmine
+	url = git://github.com/pivotal/jasmine.git

data/.travis.yml

@@ -0,0 +1,32 @@
+# Passes arguments to bundle install (http://gembundler.com/man/bundle-install.1.html)
+# bundler_args: --binstubs
+
+# Specify which versions of Ruby to run the tests on; each version will be used
+rvm:
+  - 1.8.7
+  - 1.9.2
+  
+# Define how to run the tests (defaults to `bundle exec rake` or `rake` depending on whether you have a `Gemfile`)
+# script: "bundle exec rake rspec node"
+
+# Define tasks to be completed before and after tests run. Will allow folding of content on frontend
+# before_script:
+#   - command_1
+#   - command_2
+
+# after_script:
+#   - command_1
+#   - command_2
+
+# Specify an ENV variable to run before: 'bundle install' and 'rake' (or your defined 'script')
+# env: "RAILS_ENV='test' "
+
+# Specify the recipients for email notification
+# notifications:
+#   recipients:
+#     - email-address-1
+#     - email-address-2
+
+# Disable email notifications
+# notifications:
+#   disabled: true

data/CHANGELOG

@@ -1,3 +1,126 @@
+* 1.1.0 *
+
+* If a mesh #init method does not specify any vertex normals for the mesh, and
+  Jax.Mesh#getNormalBuffer() is called, Jax.Mesh will automatically calculate
+  vertex normals for the mesh. This is a relatively expensive operation (though
+  only for the first frame or so), so you should still strive to give your own set
+  of normals when possible.
+
+* Jax.Mesh#setColor now accepts the color as a single RGBA array or as 4 separate R, G, B, A
+  arguments.
+
+* Added Jax.Geometry.Triangle, and exposed Jax.Mesh#getTriangles(). This class comes
+  complete with triangle/triangle, triangle/ray, triangle/sphere, and triangle/point
+  intersection tests! See API documentation. Jax.Geometry.Triangle can also return
+  its face normal.
+  
+* Added Jax.DataRegion, Jax.DataSegment, and Jax.DataBuffer, all of which are now used
+  internally by Jax.Mesh to manage its mesh data. This has cut memory usage for any
+  given Jax.Mesh in half, makes the additional memory footprint of Jax.Geometry.Triangle
+  negligible, and even nets a minor performance gain. Moreover, altering vertex data
+  in the Jax.Mesh is now immediately reflected in Jax.Geometry.Triangle and
+  Jax.Geometry.Plane, since they are sharing the same region of memory.
+  
+* Made most instance methods of Jax.Geometry.Plane faster and more memory efficient. Also
+  altered Jax.Geometry.Plane to take advantage of Jax.DataSegment for further memory gains.
+
+* Exposed Jax.Mesh#validate(), which makes sure the mesh has been built and builds it
+  immediately if it hasn't, or if it is out of date.
+
+* Thoroughly documented all Jax-specific extensions to the glMatrix library.
+
+* Exposed and improved Jax.Mesh#getBounds() to calculate an axis-aligned bounding box
+  (AABB) in object space, and to handle meshes with no vertices (in which case all values
+  are set to zero).
+
+* Added lib/**/*.js to the generated jasmine.yml file. (New applications only.)
+
+* Exposed Jax.Camera#frustum to the API. Improved Jax.Frustum and thoroughly documented
+  its use.
+
+* Vastly simplified usage of built-in Perlin noise. Replace all previous code with:
+
+    Jax.noise.bind(context, uniforms);
+    
+  Previous code is still compatible, but should be considered deprecated.
+  
+* Helpers can optionally be defined as arrays, rather than as functions which return
+  arrays. For example, the following two lines are equivalent to one another:
+  
+    helpers: [ UserInputHelper ]
+    helpers: function() { return [ UserInputHelper]; }
+    
+  This addition is purely to reduce typing. Use the old, function-based approach to defer
+  execution until runtime; use the array-based approach if you don't care.
+
+* Jax.Camera now uses quaternions instead of calculating the transform matrix directly.
+  This nets some potential performance improvements, but since the matrix still has to
+  eventually be calculated, it's more for internal efficiency and code maintenence than
+  anything. Using quaternions does significantly reduce the Jax.Camera memory footprint,
+  however.
+  
+* Jax.Camera now uses a fixed yaw axis by default. Use Jax.Camera#setFixedYawAxis(false)
+  to disable. The new default represents the standard camera orientation, as in first-person
+  and third-person demos. Disabling fixed yaw axis will result in a more "flight simulator"
+  type of camera.
+
+* Some minor movement-related bugfixes for Jax.Camera.
+
+* Renamed Jax.IDENTITY_MATRIX to mat4.IDENTITY for clarity and consistency.
+
+* Temporarily disabled calls to Jax.Context#checkForRenderErrors() in development under
+  Chrome, because the calls have proven far too detrimental to performance. When the
+  issue is fixed in Chrome, I'll re-enable this. In the meantime, do performance testing
+  in Chrome, but expect an overall more robust development cycle using Firefox.
+
+* App generator: added a default but customizable stylesheet and index.html used when
+  packaging apps. Affects new applications only.
+
+* Jax JavaScript library is no longer minified; this is left for developers to do after
+  packaging an application for production. This change makes it much simpler to track
+  errors in the field. May consider auto-minifying the entire package when
+  `rake package` is executed, but I'm not ready to do that yet.
+  
+* New error handling API lets developers hook directly into (and recover gracefully
+  from) otherwise catastrophic errors
+  
+* Developers can hook into "webgl not supported" errors to customize the framework's
+  response. By default, Jax redirects to an error page as per v1.0.0.
+
+* Added Rails as a dependency; Jax now internally takes advantage of Railtie
+  to implement a highly modular application structure; Jax::Plugin and
+  Jax::Application both inherit from Railtie. This is not to be confused with
+  support for or integration with Ruby on Rails.
+  
+* Controller generator now accepts the `--root` option to automatically make it the
+  root controller
+  
+* Improved the light source API so that developers can replace this:
+      this.world.addLightSource(LightSource.find("sun"));
+    with:
+      this.world.addLightSource("sun");
+
+* Jax now supports both Ruby 1.9.2 and Ruby 1.8.7.
+
+* Added a benchmark script. Internal use only, but it also demonstrates a bare-bones,
+  JavaScript-only [no Ruby counterpart] Jax application. Check it out:
+  https://github.com/sinisterchipmunk/jax/blob/1-1-stable/spec/benchmark.htm
+
+* Tons of documentation for the JavaScript API
+
+* Plugin generator to create new plugins
+
+* Plugin manager to search for, install, publish and remove plugins
+
+* Plugin Repository (http://plugins.jaxgl.com)
+
+* Plugin Guide (http://guides.jaxgl.com/plugins.html)
+
+* Jax.Context now Unregisters event handlers upon disposal
+
+* If a Jax.Context has been disposed, it will no longer render or update.
+
+
 * 1.0.1 *
 
 * If a render error is encountered while generating shadow maps, the corresponding
@@ -7,6 +130,9 @@
   a fatal error. Note that this condition is only triggered by a hard error during
   shadowmap generation; soft errors like drastically low framerates are not handled.
 
+* Driver bug workaround: avoid early returning from void functions. Apparently some
+  drivers crash when void functions encounter a `return` statement. See issue #20:
+  https://github.com/sinisterchipmunk/jax/issues/20
 
 
 * 1.0.0 *

data/README.md

@@ -1,4 +1,4 @@
-## JAX
+## JAX [![Build Status](http://travis-ci.org/sinisterchipmunk/jax.png)](http://travis-ci.org/sinisterchipmunk/jax)
 
 Jax is a framework for developing rich WebGL-enabled applications using JavaScript and Ruby.
 

data/Rakefile

@@ -10,7 +10,7 @@ rescue LoadError
   puts " *** You don't seem to have Bundler installed. ***"
   puts "     Please run the following command:"
   puts
-  puts "       gem install bundler --version=1.0.14"
+  puts "       gem install bundler --version=1.0.15"
   exit
 end
 
@@ -59,20 +59,25 @@ task :compile do
           :load_path => ["src"],
           :source_files => ["src/jax.js", "builtin/**/*.js"]
   )
-  rm_rf "dist"
-  mkdir_p "dist"
-  secretary.concatenation.save_to "dist/jax.js"
+  jax_root = File.expand_path(File.dirname(__FILE__))
+  rm_rf File.join(jax_root, "dist")
+  mkdir_p File.join(jax_root, "dist")
+  secretary.concatenation.save_to File.join(jax_root, "dist/jax.js")
+  
+  mkdir_p File.join(jax_root, "tmp") unless File.directory?(File.join(jax_root, "tmp"))
 
   # generate the built-in shaders for testing against (these are not added to the real jax dist because they are
   # regenerated in the user's app)
-  rm File.join(File.dirname(__FILE__), "tmp/shaders.js")
-  File.open(File.join(File.dirname(__FILE__), "tmp/shaders.js"), "w") do |f|
+  rm File.join(jax_root, "tmp/shaders.js") if File.file?(File.join(jax_root, "tmp/shaders.js"))
+  File.open(File.join(jax_root, "tmp/shaders.js"), "w") do |f|
     Jax.application.shaders.each { |shader| shader.save_to f }
   end
 
-  puts "generated #{File.expand_path "dist/jax.js", '.'}"
-  cp File.join(File.dirname(__FILE__), "dist/jax.js"),
-     File.join(File.dirname(__FILE__), "lib/jax/generators/app/templates/public/javascripts/jax.js")
+  puts "generated #{File.join(jax_root, "dist/jax.js")}"
+  
+  # make sure the app generator copies the correct jax
+  cp File.join(jax_root, "dist/jax.js"),
+     File.join(jax_root, "lib/jax/generators/app/templates/public/javascripts/jax.js")
   
   puts "(project built)"
 end
@@ -81,17 +86,85 @@ desc "compile and minify Jax into dist/jax.js and dist/jax-min.js"
 task :minify => :compile do
   puts "(minifying...)"
   if system("java", "-jar", File.join(File.dirname(__FILE__), "vendor/yuicompressor-2.4.2.jar"), "dist/jax.js", "-o", "dist/jax-min.js")
-    cp File.join(File.dirname(__FILE__), "dist/jax-min.js"),
-       File.join(File.dirname(__FILE__), "lib/jax/generators/app/templates/public/javascripts/jax.js")
-    puts "(done.)"
+    puts "(done. saved to: dist/jax-min.js)"
   else
     puts "(Error while minifying!)"
   end
 end
 
+### HACK to add redcloth support to pdoc without changing pdoc itself
+class PDoc::Generators::Html::Website < PDoc::Generators::AbstractGenerator
+  alias _set_markdown_parser set_markdown_parser
+  
+  def set_markdown_parser(parser = nil)
+    if parser && parser.to_sym == :redcloth
+      require 'redcloth'
+      self.class.markdown_parser = RedCloth
+    else
+      _set_markdown_parser(parser)
+    end
+  end
+end
+
 namespace :doc do
+  desc "check for common pdoc typos"
+  task :check do
+    candidates = [
+      /\/\*\*(.*?)\*\*\//m,
+      /\s*\*.*?\)\s+:/,                #  * - object (Jax.Model) : description
+      /\s*\*\s*\-.*?\)\s*\-/,          #  * - object (Jax.Model) - description
+      /\s*\*\s*\-[^\n]*?\n\s*\*\*\//m, #  * - object (Jax.Model): description\n  **/
+    ]
+    
+    errors = false
+
+    Dir[File.expand_path("src/**/*.js", File.dirname(__FILE__))].each do |fi|
+      next unless File.file?(fi)
+      lfi = fi.sub(/^#{Regexp::escape File.expand_path("src/", File.dirname(__FILE__))}\/?/, '')
+      candidates.each do |candidate|
+        if candidate.multiline?
+          content = File.read(fi)
+          offset = 0
+          lineno = 1
+          while m = candidate.match(content[offset...content.length])
+            offset += m.offset(0)[1]
+            lineno += $`.lines.to_a.length
+
+            if candidate == candidates.first
+              full = $~[0]
+              # special case -- we're looking for parameters followed by an empty line. If it's missing,
+              # pdoc will not correctly parse the params.
+              inner = $~[1]
+              
+              if inner =~ /^\s*\*\s*\-.*/m
+                lineno += $`.lines.to_a.length
+                inner = $~[0]
+                if inner !~ /\*\s*(\*|$)/m
+                  errors = true
+                  puts "#{lfi}:#{lineno} >\n#{full}"
+                end
+              end
+            else
+              errors = true
+              puts "#{lfi}:#{lineno} >\n#{$~[0]}"
+            end
+          end
+        else
+          File.read(fi).lines.each_with_index do |line,no|
+            if line =~ candidate
+              errors = true
+              puts "#{lfi}:#{no+1} > #{$~[0]}"
+            end
+          end
+        end
+      end
+    end
+    
+    exit if errors
+  end
+  
   desc "build the Jax JavaScript documentation"
-  task :js do
+  task :js => 'doc:check' do
     require 'erb'
     FileUtils.rm_rf 'doc'
     
@@ -105,7 +178,8 @@ namespace :doc do
       :destination  => "doc",
 #      :index_page   => 'src/README.markdown',
       :syntax_highlighter => 'coderay',
-      :markdown_parser    => :bluecloth,
+      :markdown_parser => :redcloth,
+      # :markdown_parser    => :bluecloth,
       :src_code_text => "View source on GitHub &rarr;",
       :src_code_href => proc { |obj|
         "https://github.com/sinisterchipmunk/jax/tree/master/#{obj.file}#L#{obj.line_number}"
@@ -156,14 +230,46 @@ namespace :guides do
   end
 end
 
+desc "Run javascript tests using node.js"
+task :node => :compile do
+  system("node", "spec/javascripts/node_helper.js")
+end
+
+FileUtils.rm_rf File.expand_path("spec/fixtures/tmp", File.dirname(__FILE__))
+require 'rake/testtask'
+desc "Run ruby tests using Test::Unit"
+# NOT WORKING due to isolation tests failing. Use test:isolated instead.
+Rake::TestTask.new("test_unit") do |t|
+  t.pattern = "{test,spec}/**/*_test.rb"
+  t.libs = ["./test", "./spec"].collect { |f| File.expand_path(f) }.select { |f| File.directory?(f) }
+#  t.verbose = true
+#  t.warning = true
+end
+
+namespace :test do
+  task :isolated do
+    dir = ENV["TEST_DIR"] || "**"
+    ruby = File.join(*RbConfig::CONFIG.values_at('bindir', 'RUBY_INSTALL_NAME'))
+    ENV['DO_NOT_ISOLATE'] = '1'
+    if ENV['TEST']
+      sh(ruby, '-Ispec', ENV['TEST'])
+    else
+      Dir["spec/#{dir}/*_test.rb"].each do |file|
+        next true if file.include?("fixtures")
+        sh(ruby, '-Ispec', File.expand_path(file, File.dirname(__FILE__)))
+      end
+    end
+  end
+end
+  
+
 # 'Guides' tasks & code borrowed from Railties.
 desc 'Generate guides (for authors), use ONLY=foo to process just "foo.textile"'
 task :guides => 'guides:generate'
 
 task :jasmine => :compile
-task :build   => [:compile, :minify]
-task :default => :compile
+# task :build   => [:compile, :minify] # make sure to minify the JS code before going to release
+task :build => :compile
 
-# we should do this before v0.0.1 but will make issues harder to track,
-# so let's hold off while in prerelease :
-# task :release => :minify
+# disabled node tests for now, since Jax.DataRegion and friends break it. Rake jasmine instead.
+task :default => ['test:isolated']#, :node]

data/bin/jax

@@ -8,4 +8,4 @@ require File.join(File.expand_path(File.dirname(__FILE__)), "../lib/jax/generato
 Jax::Generators::ScriptJaxLoader.exec_script_jax! # this uses exec so, if found, the rest of this file won't load
 
 require File.join(File.expand_path(File.dirname(__FILE__)), "../lib/jax/generators/app")
-JaxGenerator.start
+JaxAppGenerator.start