Ruby-Clutter -- Ruby bindings for Clutter-1.6.x
===============================================

This is a set of bindings for the Clutter 1.6.x libraries for use from
Ruby.

This particular branch was started in 2009 to add support for Clutter
1.0 to the Ruby bindings, which no longer appeared to be maintained
(this is still apparently so in 2011).  This isn't a complete port.
Clutter-cairo, in particular, has been disabled, and some of the newer
API may be missing (although I've been trying to add most of it).

This has been tested with Clutter 1.6 (at least as far as building
goes).

Please note that there is another project on GitHub which has done the
same, but has not ported the GStreamer bindings among other things.  I
haven't been arsed to properly merge them, if there's anything that it
covers that I don't.

https://github.com/mieko/rbclutter-unofficial

Install
-------

Note that you'll want the headers installed for Ruby Glib (from the
Ruby GNOME2 project), including those for gstreamer and gtk (if you
elect to use those components).

 1. ruby extconf.rb
 2. make
 3. su
 4. make install

Dependencies
------------

To install the bindings the following is also needed:

 - Ruby ~> 1.8
 - Clutter ~> 1.6.x
 - Ruby-GNOME2 glib/gobject bindings

The optional clutter-gtk bindings depend on the Ruby GTK+ bindings,
clutter-cairo depends on the Ruby cairo bindings, and clutter-gst
depends on the Ruby gstreamer bindings.  All of these are available
from the Ruby GNOME2 project, at:

http://ruby-gnome2.sourceforge.jp/

Issues
------

* Examples are all broken
* A systematic trip needed through the entire API to add anything
  missing
* There are a lot of warnings, the results of both bugs and
  deprecations.  They were hidden before because -Wall wasn't enabled.
* Thanks to GIR, https://github.com/mvz/ruby-gir-ffi is probably going
  to entirely obsolete this before too long.

Here is my quick list of things that are (probably) missing.  I might
have marked some things that are internal by mistake:

action
actor-meta
animatable
animator
bezier ?
binding-pool ?
cairo-texture
click-action
clone
deform-effect
desaturate-effect
colorize-effect
offscreen-effect
page-turn-effect
blur-effect
shader-effect
device-manager
drag-action
effect
event-translator ?
fixed ?
id-pool ? 
input-device
interval ? 
master-clock ?
paint-volume ?
profile ?
script-parser ?
settings
shader-types ?
snap-constraint
stage-window ?
state
table-layout
timeout-interval ?
timeout-pool ?
units
util

I imagine that this list from the original project is still mostly
true:

There's a few issues to be aware of with this release:

 - There's no documentation, however the method names try to follow
   the same system as the Ruby GTK bindings so you can generally read
   the Clutter API documentation and guess the Ruby method. See this
   page for details: http://tinyurl.com/3btpoq

 - There's no way to implement an interface or override a GObject
   method in Ruby code yet. So for example, you can create a Ruby
   object that is a subclass of Clutter::Actor, register it as a new
   GType and create custom signals, but you can not implement the
   ClutterContainer interface.

 - There are bindings for clutter_threads_enter and
   clutter_threads_leave but you shouldn't need to call these
   functions if you are just using regular Ruby threads. Ruby does not
   use native threads so there is no need to lock Clutter. If you do
   try to grab the Clutter lock in two separate Ruby threads then the
   process will block forever because Ruby will not be given a chance
   to switch threads while waiting for clutter_threads_enter to
   complete. It can however be used in combination with another
   library that may create native threads.

 - The effect functions can't take a callback block for when the
   effect is complete, even though the C API has a parameter for
   it. I'm hoping Clutter will eventually get a GDestroyNotify
   parameter for the effect functions which would make this a lot
   easier.

 - Clutter::init isn't explictly called for you when you execute
   'require "clutter"'. That way you can optionally use your own
   argument array instead of ARGV. However, there appears to be a
   problem wrapping clutter-gst before gst_init is called, so if you
   execute 'require "clutter_gst"' it *will* explicitly call
   clutter_gst_init.