opengl.xml

<?xml version="1.0" encoding="UTF-8"?>
<appendix id="opengl">
  <title>Using OpenGL with FXRuby</title>

  <abstract>
    <para>FOX provides extensive support for OpenGL through its
    <classname>FXGLCanvas</classname> and <classname>FXGLViewer</classname>
    widgets, and FXRuby in turn provides interfaces to those classes. By
    combining FXRuby with the OpenGL interface for Ruby (described below) you
    can develop very powerful 3-D graphics applications. This chapter gives
    you the information you'll need to get started.</para>
  </abstract>

  <simplesect>
    <title>What is OpenGL?</title>

    <para>OpenGL is a platform-independent API for 2D and 3D graphics. The
    home page is <ulink
    url="http://www.opengl.org">http://www.opengl.org</ulink>. Because it's a
    fairly open standard, highly optimized OpenGL drivers are available for
    most operating systems (including Windows and Linux).</para>
  </simplesect>

  <simplesect>
    <title>OpenGL Extensions for Ruby</title>

    <para>The <ulink url="http://ruby-opengl.rubyforge.org/">ruby-opengl</ulink> extension module, originally developed by Yoshiyuki Kusano and
        currently maintained by Alain Hoang, provides
    interfaces to not only the basic OpenGL API, but also the GLU and GLUT
    APIs. As of this writing, the currently released version is 0.60.1.
    You can install it by typing:</para>

    <screen>$ <command>gem install ruby-opengl</command></screen>

    <para>Please note that since I'm not the maintainer of this particular Ruby
    extension, so I can't really accept bug fixes for it. But if you're having
    trouble integrating Ruby/OpenGL with FXRuby, let me know and we'll see
    what we can do.</para>
  </simplesect>

  <simplesect>
    <title>The FXGLVisual Class</title>

    <para>An <classname>FXGLVisual</classname> object describes the
    capabilities of an <classname>FXGLCanvas</classname> or
    <classname>FXGLViewer</classname> window. Typically, an X server supports
    many different visuals with varying capabilities, but the ones with
    greater capabilities require more resources than those with fewer
    capbilities. To construct an <classname>FXGLVisual</classname> object,
    just call <methodname>FXGLVisual.new</methodname>:</para>

    <programlisting format="linespecific">aVisual = FXGLVisual.new(theApp, VISUAL_DOUBLEBUFFER)</programlisting>

    <para>The first argument to <methodname>FXGLVisual.new</methodname> is a
    reference to the application object. The second argument is a set of
    options indicating the <emphasis>requested</emphasis> capabilities for the
    visual. If one or more of the requested capabilities aren't available, FOX
    will try to gracefully degrade to a working GL visual; but if you're
    counting on a specific capability, be sure to check the returned visual to
    see if it actually supports that capability. For example, say you request
    a visual with double-buffering and stereographic capabilities:</para>

    <programlisting format="linespecific">anotherVisual = FXGLVisual.new(theApp, VISUAL_DOUBLEBUFFER | VISUAL_STEREO)</programlisting>

    <para>Double-buffering is pretty commonplace these days, but stereo may
    not be available on the system. We can check to see whether the visual we
    got supports these capabilities by calling the
    <methodname>FXGLVisual#doubleBuffered?</methodname> and
    <methodname>FXGLVisual#stereo?</methodname> methods:</para>

    <programlisting format="linespecific">anotherVisual = FXGLVisual.new(theApp, VISUAL_DOUBLEBUFFER | VISUAL_STEREO)
if anotherVisual.doubleBuffered?
  puts "It's double-buffered."
else
  puts "It's single-buffered."
end
if anotherVisual.stereo?
  puts "It's stereo."
else
  puts "It isn't stereo."
end</programlisting>

    <para>Some <classname>FXGLVisual</classname> object must be associated
    with every <classname>FXGLCanvas</classname> or
    <classname>FXGLViewer</classname> window, but you don't need to have a
    separate <classname>FXGLVisual</classname> object for each window. For
    most applications, you can just construct a single
    <classname>FXGLVisual</classname> object that's shared among all the
    OpenGL windows.</para>
  </simplesect>

  <simplesect>
    <title>The FXGLCanvas Class</title>

    <para>The <classname>FXGLCanvas</classname> widget provides a very simple
    OpenGL-capable window with minimal functionality. To construct an
    <classname>FXGLCanvas</classname>, call
    <methodname>FXGLCanvas.new</methodname>:</para>

    <programlisting format="linespecific">glCanvas = FXGLCanvas.new(parent, vis)</programlisting>

    <para>The first argument to <methodname>FXGLCanvas.new</methodname> is the
    parent (container) widget and the second argument is the
    <classname>FXGLVisual</classname> that should be used for this
    window.</para>
  </simplesect>

  <simplesect>
    <title>OpenGL objects and the FXGLViewer</title>

    <para>The <classname>FXGLViewer</classname> widget provides a higher-level
    OpenGL-capable window with a lot of built-in functionality. To construct
    an <classname>FXGLViewer</classname>, call
    <methodname>FXGLViewer.new</methodname>:</para>

    <programlisting format="linespecific">glViewer = FXGLViewer.new(parent, vis)</programlisting>

    <para>The first argument to <methodname>FXGLViewer.new</methodname> is the
    parent (container) widget and the second argument is the
    <classname>FXGLVisual</classname> that should be used for this
    window.</para>
  </simplesect>
</appendix>