3D Graphics Library for Ruby.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci
bin Initial Commit Jul 13, 2015
examples add: lathe geometry Sep 17, 2018
lib add: lathe geometry Sep 17, 2018
test add: lathe geometry Sep 17, 2018
.codeclimate.yml chore: set up codeclimate config Feb 18, 2016
.gitignore feat: JUnit minitest reports for CI Feb 21, 2016
.rubocop.yml chore: set up codeclimate config Feb 18, 2016
CODE_OF_CONDUCT.md Initial Commit Jul 13, 2015
Gemfile patch: use code climate and coveralls together Feb 23, 2016
LICENSE.txt patch: update LICENSE to include 2016 Feb 21, 2016
README.md
Rakefile test: buffer attribute class Jul 13, 2015
appveyor.yml fix: missed a win64 in appveyor.yml Jan 5, 2017
install-glfw-3.1.2.sh patch: check for glfw .so instead of .a Feb 21, 2016
install_glfw.ps1 use win32 glfw on appveyor Jan 5, 2017
mittsu.gemspec patch: remove imagemagick requirement from gemspec Jan 5, 2017
run_all_examples.sh patch: use [0-9] for grep as the d shorthand is not compatible with a… Apr 7, 2016

README.md

Mittsu

Gem Version Dependency Status Coverage Status Code Climate

🍎 Circle CI Build Status (macOS)   🐧 Travis Build Status (Ubuntu)   🖼 AppVeyor Build status (Windows)

3D Graphics Library for Ruby

Mittsu makes 3D graphics easier by providing an abstraction over OpenGL, and is based heavily off of THREE.js. No more weird pointers and wondering about the difference between a VAO and a VBO (besides the letter). Simply think of something awesome and make it!

GIFs!

Normal-mapped Earth Point Light Tank Demo

(You can find the source for the Tank Demo here)

Installation

Install the prerequisites:

Mittsu depends on Ruby 2.x, OpenGL 3.3+, and GLFW 3.1.x

# OSX
$ brew install glfw3

# Ubuntu
$ sudo apt-get install libglfw3

NOTE: On Windows, you will have to manually specify the glfw3.dll path in an environment variable (you can download it here)

> set MITTSU_LIBGLFW_PATH=C:\path\to\glfw3.dll
> ruby your_awesome_mittsu_app.rb

Add this line to your application's Gemfile:

gem 'mittsu'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mittsu

Usage

tl;dr

Copy-Paste and Run:

require 'mittsu'

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
ASPECT = SCREEN_WIDTH.to_f / SCREEN_HEIGHT.to_f

renderer = Mittsu::OpenGLRenderer.new width: SCREEN_WIDTH, height: SCREEN_HEIGHT, title: 'Hello, World!'

scene = Mittsu::Scene.new

camera = Mittsu::PerspectiveCamera.new(75.0, ASPECT, 0.1, 1000.0)
camera.position.z = 5.0

box = Mittsu::Mesh.new(
  Mittsu::BoxGeometry.new(1.0, 1.0, 1.0),
  Mittsu::MeshBasicMaterial.new(color: 0x00ff00)
)

scene.add(box)

renderer.window.run do
  box.rotation.x += 0.1
  box.rotation.y += 0.1

  renderer.render(scene, camera)
end

Step by Step

First, we need to require Mittsu in order to use it:

require 'mittsu'

Then, we'll define some constants to help us with setting up our 3D environment:

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
ASPECT = SCREEN_WIDTH.to_f / SCREEN_HEIGHT.to_f

The aspect ratio will be used for setting up the camera later.

Once we have all that we can create the canvas we will use to draw our graphics onto. In Mittsu this is called a renderer. It provides a window and an OpenGL context:

renderer = Mittsu::OpenGLRenderer.new width: SCREEN_WIDTH, height: SCREEN_HEIGHT, title: 'Hello, World!'

This will give us an 800x600 window with the title Hello, World!.

Now that we have our canvas, let's start setting up the scene we wish to draw onto it:

scene = Mittsu::Scene.new

A scene is like a stage where all our 3D objects live and animate.

We can't draw a 3D scene without knowing where we're looking:

camera = Mittsu::PerspectiveCamera.new(75.0, ASPECT, 0.1, 1000.0)

This camera has a 75° field-of-view (FOV), the aspect ratio of the window (which we defined earlier), and shows everything between a distance of 0.1 to 1000.0 away from the camera.

The camera starts off at the origin [0,0,0] and faces the negative Z-axis. We'll position it somewhere along the positive Z-axis so that it is looking at the center of the scene from a short distance:

camera.position.z = 5.0

Our scene isn't going to be very exciting if there is nothing in it, so we'll create a box:

box = Mittsu::Mesh.new(
  Mittsu::BoxGeometry.new(1.0, 1.0, 1.0),
  Mittsu::MeshBasicMaterial.new(color: 0x00ff00)
)

A Mesh in Mittsu is the combination of a Geometry (the shape of the object) and a Material (the "look" of the object). Here we've created a 1x1x1 box that is colored green.

Box in hand, we make it part of our scene:

scene.add(box)

Here comes the fun part... the render loop!

renderer.window.run do

The given block is called every frame. This is where you can tell the renderer what scene to draw, and do any updates to the objects in your scene.

Just to make things a bit more interesting, we'll make the box rotate around its X and Y axes, so that it spins like crazy.

box.rotation.x += 0.1
box.rotation.y += 0.1

Last but not least, we tell the renderer to draw our scene this frame, which will tell the graphics processor to draw our green box with its updated rotation.

renderer.render(scene, camera)

Easy peasy! :)

end

More Resources

Mittsu follows a similar structure to THREE.js, so you can generally use the same documentation for a description of the various classes and how they work.

If you just want to see what Mittsu can do and how to do it, take a peek inside the examples folder.

Where you can help

  1. Testing!

    Currently the only unit tests are for most of the maths library, otherwise the library is tested by running the examples and checking that they look correct.

  2. Refactoring!

    The code is unfortunately still a mess. Mittsu started out as a direct port of THREE.js, and JavaScript to Ruby is not an exact science.

  3. Find Bugs!

    Mittsu is still very young, and there are plenty of small bugs and glitches that need to be ironed out. If you find a bug, create an issue so we can track it and squash it.

  4. Add all the features!

    Some of the things I'd like to see ported from THREE.js include:

    • Picking (clicking on 3D objects in a scene)
    • Bone structure/animation (e.g. for character movements)
    • Lens Flares! (for JJ Abrams)
    • All the Extras and Helpers (who doesn't need extra help?)
  5. Write documentation!

    You can use the same docs as THREE.js for now, but I would like to provide Mittsu-specific documentation so devs don't have to keep replacing new THREE.Thing() with Mittsu::Thing.new.

Contributing

  1. Fork it ( https://github.com/jellymann/mittsu/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Thank you for helping me help you help us all. ;)